@gunshi/plugin-completion 0.27.0-alpha.8 → 0.27.0-alpha.9

package/README.md

@@ -1,14 +1,240 @@
-# `@gunshi/plugin-completion`
+# @gunshi/plugin-completion
 
-> completion plugin for gunshi
+> shell completion plugin for gunshi.
+
+This plugin provides tab completion functionality for your CLI applications, allowing users to auto-complete commands, options, and arguments in their shell. It generates shell-specific completion scripts and handles runtime completion suggestions.
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!WARNING]
+> This package support Node.js runtime only. Deno and Bun support are coming soon.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## 💿 Installation
+
+```sh
+# npm
+npm install --save @gunshi/plugin-completion
+
+# pnpm
+pnpm add @gunshi/plugin-completion
+
+# yarn
+yarn add @gunshi/plugin-completion
+
+# deno
+deno add jsr:@gunshi/plugin-completion
+
+# bun
+bun add @gunshi/plugin-completion
+```
+
+## 🚀 Usage
+
+```ts
+import { cli } from 'gunshi'
+import completion from '@gunshi/plugin-completion'
+
+const command = {
+  name: 'deploy',
+  args: {
+    environment: {
+      type: 'string',
+      short: 'e',
+      description: 'Target environment'
+    },
+    config: {
+      type: 'string',
+      short: 'c',
+      description: 'Config file path'
+    }
+  },
+  run: ctx => {
+    console.log(`Deploying to ${ctx.values.environment}`)
+  }
+}
+
+await cli(process.argv.slice(2), command, {
+  name: 'my-cli',
+  version: '1.0.0',
+  plugins: [
+    completion({
+      config: {
+        entry: {
+          args: {
+            config: {
+              handler: () => [
+                { value: 'prod.json', description: 'Production config' },
+                { value: 'dev.json', description: 'Development config' },
+                { value: 'test.json', description: 'Test config' }
+              ]
+            }
+          }
+        }
+      }
+    })
+  ]
+})
+```
+
+## ✨ Features
+
+### Automatic Complete Command
+
+The plugin automatically adds a `complete` subcommand to your CLI:
+
+```bash
+# Generate shell completion script
+my-cli complete bash > ~/.my-cli-completion.bash
+source ~/.my-cli-completion.bash
+
+# Now tab completion works!
+my-cli dep<TAB>  # Completes to: my-cli deploy
+my-cli deploy --env<TAB>  # Completes to: my-cli deploy --environment
+```
+
+### Shell Support
+
+The `complete` command accepts the following shell types:
+
+- `bash` - Bash shell completion
+- `zsh` - Zsh shell completion
+- `fish` - Fish shell completion
+
+### Custom Completion Handlers
+
+You can provide custom completion handlers for specific arguments:
+
+```ts
+completion({
+  config: {
+    entry: {
+      args: {
+        environment: {
+          handler: ({ locale }) => [
+            { value: 'production', description: 'Production environment' },
+            { value: 'staging', description: 'Staging environment' },
+            { value: 'development', description: 'Development environment' }
+          ]
+        }
+      }
+    },
+    subCommands: {
+      deploy: {
+        args: {
+          region: {
+            handler: ({ previousArgs }) => {
+              // Dynamic completions based on previous arguments
+              const env = previousArgs.find(arg => arg.startsWith('--environment='))
+              if (env?.includes('production')) {
+                return [
+                  { value: 'us-east-1', description: 'US East (N. Virginia)' },
+                  { value: 'eu-west-1', description: 'EU (Ireland)' }
+                ]
+              }
+              return [{ value: 'local', description: 'Local development' }]
+            }
+          }
+        }
+      }
+    }
+  }
+})
+```
+
+### Internationalization Support
+
+When used with `@gunshi/plugin-i18n`, completion descriptions are automatically localized:
+
+```ts
+import completion from '@gunshi/plugin-completion'
+import i18n from '@gunshi/plugin-i18n'
+
+await cli(args, command, {
+  plugins: [
+    i18n({ locale: 'ja-JP' }),
+    completion() // Descriptions will be shown in Japanese
+  ]
+})
+```
+
+## ⚙️ Plugin Options
+
+### `config`
+
+- Type: `{ entry?: CompletionConfig, subCommands?: Record<string, CompletionConfig> }`
+- Default: `{}`
+- Description: Configuration for completion handlers
+
+#### CompletionConfig
+
+```ts
+interface CompletionConfig {
+  handler?: CompletionHandler // Handler for command-level completions
+  args?: Record<
+    string,
+    {
+      // Handlers for specific arguments
+      handler: CompletionHandler
+    }
+  >
+}
+```
+
+#### CompletionHandler
+
+```ts
+type CompletionHandler = (params: {
+  previousArgs: string[] // Previously entered arguments
+  toComplete: string // Current string being completed
+  endWithSpace: boolean // Whether input ends with space
+  locale?: Intl.Locale // Current locale (if i18n is enabled)
+}) => CompletionItem[]
+
+interface CompletionItem {
+  value: string // The completion value
+  description?: string // Optional description
+}
+```
+
+## 🔗 Plugin Dependencies
+
+The completion plugin has an optional dependency on the i18n plugin:
+
+- **Plugin ID**: `g:i18n` (optional)
+- **Purpose**: Provides localized descriptions for completions
+- **Effect**: When the i18n plugin is present, all command and argument descriptions are automatically translated to the current locale
+
+## 🧩 Context Extensions
+
+When using the completion plugin, your command context is extended via `ctx.extensions['g:completion']`.
 
 <!-- eslint-disable markdown/no-missing-label-refs -->
 
-> ![WARNING]
-> This package is still work in progress
+> [!IMPORTANT]
+> This plugin extension is namespaced in `CommandContext.extensions` using this plugin ID `g:completion` by the gunshi plugin system.
 
 <!-- eslint-enable markdown/no-missing-label-refs -->
 
+Currently, the completion plugin does not provide any context extensions for use within commands. The plugin ID can be imported for type-safe access:
+
+```ts
+import completion, { pluginId } from '@gunshi/plugin-completion'
+```
+
+## 📚 API References
+
+See the [API References](./docs/index.md)
+
+## 💖 Credits
+
+This project uses and depends on:
+
+- [`@bombsh/tab`](https://github.com/bombshell-dev/tab), created by [Bombshell](https://github.com/bombshell-dev) - Shell completion library
+
+Thank you!
+
 ## ©️ License
 
 [MIT](http://opensource.org/licenses/MIT)

package/lib/index.d.ts

@@ -1,5 +1,9 @@
-import { PluginWithExtension } from "@gunshi/plugin";
-import { Handler } from "@bombsh/tab";
+/*! license ISC 
+ * @author Bombshell team and Bombshell contributors
+ * Bombshell related codes are forked from @bombsh/tab
+ */
+
+import { PluginWithoutExtension } from "@gunshi/plugin";
 
 //#region ../shared/src/constants.d.ts
 /**
@@ -23,6 +27,15 @@ type GenerateNamespacedKey<Key extends string, Prefixed extends string = typeof
 /**
  * Command i18n built-in arguments keys.
  */
+
+//#endregion
+//#region src/bombshell/index.d.ts
+
+type Item = {
+  description: string;
+  value: string;
+};
+type Handler = (previousArgs: string[], toComplete: string, endsWithSpace: boolean) => Item[] | Promise<Item[]>;
 //#endregion
 //#region src/types.d.ts
 /**
@@ -33,6 +46,19 @@ declare const pluginId: GenerateNamespacedKey<'completion', typeof PLUGIN_PREFIX
  * Type representing the unique identifier for the completion plugin.
  */
 type PluginId = typeof pluginId;
+/**
+ * Parameters for {@link CompletionHandler | the completion handler}.
+ */
+interface CompletionParams {
+  previousArgs: Parameters<Handler>[0];
+  toComplete: Parameters<Handler>[1];
+  endWithSpace: Parameters<Handler>[2];
+  locale?: Intl.Locale;
+}
+/**
+ * The handler for completion.
+ */
+type CompletionHandler = (params: CompletionParams) => ReturnType<Handler>;
 /**
  * Extended command context which provides utilities via completion plugin.
  * These utilities are available via `CommandContext.extensions['g:completion']`.
@@ -42,9 +68,9 @@ interface CompletionCommandContext {}
  * Completion configuration, which structure is similar `bombsh/tab`'s `CompletionConfig`.
  */
 interface CompletionConfig {
-  handler?: Handler;
+  handler?: CompletionHandler;
   args?: Record<string, {
-    handler: Handler;
+    handler: CompletionHandler;
   }>;
 }
 /**
@@ -67,6 +93,6 @@ interface CompletionOptions {
 /**
  * completion plugin for gunshi
  */
-declare function completion(options?: CompletionOptions): PluginWithExtension<CompletionCommandContext>;
+declare function completion(options?: CompletionOptions): PluginWithoutExtension;
 //#endregion
-export { CompletionCommandContext, CompletionConfig, CompletionOptions, PluginId, completion as default, pluginId };
+export { CompletionCommandContext, CompletionConfig, CompletionHandler, CompletionOptions, CompletionParams, PluginId, completion as default, pluginId };

package/lib/index.js

@@ -1,6 +1,195 @@
-import { plugin } from "@gunshi/plugin";
+/*! license ISC 
+ * @author Bombshell team and Bombshell contributors
+ * Bombshell related codes are forked from @bombsh/tab
+ */
 
-//#region ../../node_modules/.pnpm/tab@https+++pkg.pr.new+bombshell-dev+tab@main/node_modules/tab/dist/zsh-Bm75fLuV.js
+import { CLI_OPTIONS_DEFAULT, createCommandContext, plugin } from "@gunshi/plugin";
+
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/utils-N7UlhLbz.js
+/**
+* Entry point of utils.
+*
+* Note that this entry point is used by gunshi to import utility functions.
+*
+* @module
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+function kebabnize(str) {
+	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
+}
+
+//#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}`;
+const ARG_NEGATABLE_PREFIX = "no-";
+
+//#endregion
+//#region ../resources/locales/en-US.json
+var COMMAND = "COMMAND";
+var COMMANDS = "COMMANDS";
+var SUBCOMMAND = "SUBCOMMAND";
+var USAGE = "USAGE";
+var ARGUMENTS = "ARGUMENTS";
+var OPTIONS = "OPTIONS";
+var EXAMPLES = "EXAMPLES";
+var FORMORE = "For more info, run any command with the `--help` flag";
+var NEGATABLE = "Negatable of";
+var DEFAULT = "default";
+var CHOICES = "choices";
+var help = "Display this help message";
+var version = "Display this version";
+var en_US_default = {
+	COMMAND,
+	COMMANDS,
+	SUBCOMMAND,
+	USAGE,
+	ARGUMENTS,
+	OPTIONS,
+	EXAMPLES,
+	FORMORE,
+	NEGATABLE,
+	DEFAULT,
+	CHOICES,
+	help,
+	version
+};
+
+//#endregion
+//#region ../shared/src/utils.ts
+/**
+* Resolve a namespaced key for argument resources.
+* Argument keys are prefixed with "arg:".
+* If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:arg:foo").
+* @param key The argument key to resolve.
+* @param ctx The command context.
+* @returns Prefixed argument key.
+*/
+function resolveArgKey(key, ctx) {
+	return `${ctx?.name ? `${ctx.name}${BUILT_IN_KEY_SEPARATOR}` : ""}${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+}
+/**
+* Resolve a namespaced key for non-built-in resources.
+* Non-built-in keys are not prefixed with any special characters. If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:foo").
+* @param key The non-built-in key to resolve.
+* @param ctx The command context.
+* @returns Prefixed non-built-in key.
+*/
+function resolveKey(key, ctx) {
+	return `${ctx?.name ? `${ctx.name}${BUILT_IN_KEY_SEPARATOR}` : ""}${key}`;
+}
+async function resolveExamples(ctx, examples) {
+	return typeof examples === "string" ? examples : typeof examples === "function" ? await examples(ctx) : "";
+}
+function namespacedId(id) {
+	return `${PLUGIN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${id}`;
+}
+function makeShortLongOptionPair(schema, name, toKebab) {
+	const displayName = toKebab || schema.toKebab ? kebabnize(name) : name;
+	let key = `--${displayName}`;
+	if (schema.short) key = `-${schema.short}, ${key}`;
+	return key;
+}
+
+//#endregion
+//#region ../shared/src/localization.ts
+/**
+* Create a localizable function for a command.
+* This function will resolve the translation key based on the command context and the provided translation function.
+* @param ctx Command context
+* @param cmd Command
+* @param translate Translation function
+* @returns Localizable function
+*/
+function localizable(ctx, cmd, translate) {
+	async function localize(key, values) {
+		if (translate) return translate(key, values);
+		if (key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR)) {
+			const resKey = key.slice(BUILD_IN_PREFIX_AND_KEY_SEPARATOR.length);
+			return en_US_default[resKey] || key;
+		}
+		const namaspacedArgKey = resolveKey(ARG_PREFIX_AND_KEY_SEPARATOR, ctx);
+		if (key.startsWith(namaspacedArgKey)) {
+			let argKey = key.slice(namaspacedArgKey.length);
+			let negatable = false;
+			if (argKey.startsWith(ARG_NEGATABLE_PREFIX)) {
+				argKey = argKey.slice(ARG_NEGATABLE_PREFIX.length);
+				negatable = true;
+			}
+			const schema = ctx.args[argKey];
+			if (!schema) return argKey;
+			return negatable && schema.type === "boolean" && schema.negatable ? `${en_US_default["NEGATABLE"]} ${makeShortLongOptionPair(schema, argKey, ctx.toKebab)}` : schema.description || "";
+		}
+		if (key === resolveKey("description", ctx)) return "";
+		else if (key === resolveKey("examples", ctx)) return await resolveExamples(ctx, cmd.examples);
+		else return key;
+	}
+	return localize;
+}
+
+//#endregion
+//#region src/bombshell/bash.ts
 function generate$3(name, exec) {
 	const nameForVar = name.replace(/[-:]/g, "_");
 	const ShellCompDirectiveError = ShellCompDirective.ShellCompDirectiveError;
@@ -32,31 +221,31 @@ __${nameForVar}_complete() {
     _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
@@ -67,7 +256,7 @@ __${nameForVar}_complete() {
     if [[ $((directive & $ShellCompDirectiveNoFileComp)) -ne 0 ]]; then
         compopt +o default
     fi
-    
+
     # Handle file extension filtering
     if [[ $((directive & $ShellCompDirectiveFilterFileExt)) -ne 0 ]]; then
         local filter=""
@@ -79,18 +268,18 @@ __${nameForVar}_complete() {
         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
@@ -103,7 +292,7 @@ __${nameForVar}_complete() {
             completions+=("$comp")
         fi
     done <<< "$out"
-    
+
     # Return completions
     COMPREPLY=( $(compgen -W "\${completions[*]}" -- "$cur") )
 }
@@ -112,6 +301,9 @@ __${nameForVar}_complete() {
 complete -F __${nameForVar}_complete ${name}
 `;
 }
+
+//#endregion
+//#region src/bombshell/fish.ts
 function generate$2(name, exec) {
 	const nameForVar = name.replace(/[-:]/g, "_");
 	const ShellCompDirectiveError = ShellCompDirective.ShellCompDirectiveError;
@@ -142,16 +334,16 @@ function __${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"
 
@@ -159,7 +351,7 @@ function __${nameForVar}_perform_completion
     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
@@ -171,12 +363,12 @@ function __${nameForVar}_perform_completion
             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
@@ -211,14 +403,14 @@ function __${nameForVar}_perform_completion
             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
@@ -234,7 +426,7 @@ function __${nameForVar}_perform_completion
                 set -a dirs "$item/"
             end
         end
-        
+
         for item in $dirs
             echo -e "$item\t"
         end
@@ -249,7 +441,7 @@ function __${nameForVar}_perform_completion
                 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
@@ -258,12 +450,12 @@ function __${nameForVar}_perform_completion
             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
 
@@ -271,7 +463,10 @@ end
 complete -c ${name} -f -a "(eval __${nameForVar}_perform_completion)"
 `;
 }
-function generate$1(name, exec, includeDesc = false) {
+
+//#endregion
+//#region src/bombshell/powershell.ts
+function generate$1(name, exec, _includeDesc = false) {
 	const nameForVar = name.replace(/[-:]/g, "_");
 	const ShellCompDirectiveError = ShellCompDirective.ShellCompDirectiveError;
 	const ShellCompDirectiveNoSpace = ShellCompDirective.ShellCompDirectiveNoSpace;
@@ -526,199 +721,9 @@ function generate$1(name, exec, includeDesc = false) {
 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}`);
-	}
-}
+
+//#endregion
+//#region src/bombshell/zsh.ts
 function generate(name, exec) {
 	return `#compdef ${name}
 compdef _${name} ${name}
@@ -939,72 +944,199 @@ 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}`);
+//#region src/bombshell/index.ts
+const ShellCompDirective = {
+	ShellCompDirectiveError: Math.trunc(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);
 		}
-	} 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 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);
+				break;
+			}
+		}
+		return [matched, remaining];
+	}
+	async parse(args) {
+		const endsWithSpace = args.at(-1) === "";
+		if (endsWithSpace) args.pop();
+		let toComplete = args.at(-1) || "";
+		const previousArgs = args.slice(0, -1);
+		if (endsWithSpace) {
+			previousArgs.push(toComplete);
+			toComplete = "";
+		}
+		const [matchedCommand] = this.matchCommand(previousArgs);
+		const lastPrevArg = previousArgs.at(-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();
+		for (const comp of this.completions.filter((comp$1) => {
+			if (seen.has(comp$1.value)) return false;
+			seen.add(comp$1.value);
+			return true;
+		}).filter((comp$1) => comp$1.value.startsWith(toComplete))) 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}`);
 	}
-	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
@@ -1016,10 +1148,27 @@ const pluginId = namespacedId("completion");
 
 //#endregion
 //#region src/utils.ts
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
+async function createCommandContext$1(cmd, id, i18n) {
+	const extensions = Object.create(null);
+	if (i18n) extensions[id] = {
+		key: Symbol(id),
+		factory: () => i18n
+	};
+	return await createCommandContext({
+		args: cmd.args || Object.create(null),
+		values: Object.create(null),
+		positionals: [],
+		rest: [],
+		argv: [],
+		explicit: Object.create(null),
+		tokens: [],
+		omitted: false,
+		callMode: cmd.entry ? "entry" : "subCommand",
+		command: cmd,
+		extensions,
+		cliOptions: CLI_OPTIONS_DEFAULT
+	});
+}
 function detectRuntime() {
 	if (globalThis.process !== void 0 && globalThis.process.release?.name === "node") return "node";
 	if (globalThis.Deno !== void 0) return "deno";
@@ -1052,6 +1201,7 @@ const TERMINATOR = "--";
 const NOOP_HANDLER = () => {
 	return [];
 };
+const i18nPluginId = namespacedId("i18n");
 /**
 * completion plugin for gunshi
 */
@@ -1061,6 +1211,10 @@ function completion(options = {}) {
 	return plugin({
 		id: pluginId,
 		name: "completion",
+		dependencies: [{
+			id: i18nPluginId,
+			optional: true
+		}],
 		async setup(ctx) {
 			/**
 			* add command for completion script generation
@@ -1069,6 +1223,7 @@ function completion(options = {}) {
 			ctx.addCommand(completeName, {
 				name: completeName,
 				description: "Generate shell completion script",
+				rendering: { header: null },
 				run: async (cmdCtx) => {
 					if (!cmdCtx.env.name) throw new Error("your cli name is not defined.");
 					let shell = cmdCtx._[1];
@@ -1079,46 +1234,63 @@ function completion(options = {}) {
 					} else script(shell, cmdCtx.env.name, quoteExec());
 				}
 			});
-			/**
-			* disable header renderer
-			*/
-			ctx.decorateHeaderRenderer(async (_baseRenderer, _cmdCtx) => "");
 		},
-		extension: (_ctx, _cmd) => {
-			return {};
-		},
-		onExtension: async (ctx, _cmd) => {
+		onExtension: async (ctx, cmd) => {
+			const i18n = ctx.extensions?.[i18nPluginId];
 			const subCommands = ctx.env.subCommands;
-			const entry = [...subCommands].map(([_, cmd]) => cmd).find((cmd) => cmd.entry);
+			const entry = [...subCommands].map(([_, cmd$1]) => cmd$1).find((cmd$1) => cmd$1.entry);
 			if (!entry) throw new Error("entry command not found.");
+			const entryCtx = await createCommandContext$1(entry, i18nPluginId, i18n);
+			if (i18n) {
+				const ret = await i18n.loadResource(i18n.locale, entryCtx, entry);
+				if (!ret) console.warn(`Failed to load i18n resources for command: ${entry.name} (${i18n.locale})`);
+			}
+			const localizeDescription = localizable(entryCtx, cmd, i18n ? i18n.translate : void 0);
 			const isPositional = hasPositional(await resolveLazyCommand(entry));
 			const root = "";
-			completion$1.addCommand(root, entry.description || "", isPositional ? [false] : [], NOOP_HANDLER);
+			completion$1.addCommand(root, await localizeDescription(resolveKey("description", entryCtx)) || 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);
+				completion$1.addOption(root, `--${key}`, await localizeDescription(resolveArgKey(key, entryCtx)) || schema.description || "", toBombshellCompletionHandler(config.entry?.args?.[key]?.handler || NOOP_HANDLER, i18n ? toLocale(i18n.locale) : void 0), schema.short);
 			}
-			await handleSubCommands(completion$1, subCommands, config.subCommands);
+			await handleSubCommands(completion$1, subCommands, config.subCommands, i18nPluginId, i18n);
 		}
 	});
 }
-async function handleSubCommands(completion$1, subCommands, configs = {}) {
+async function handleSubCommands(completion$1, subCommands, configs = {}, i18nPluginId$1, i18n) {
 	for (const [name, cmd] of subCommands) {
 		if (cmd.internal || cmd.entry || name === "complete") continue;
 		const resolvedCmd = await resolveLazyCommand(cmd);
+		const ctx = await createCommandContext$1(resolvedCmd, i18nPluginId$1, i18n);
+		if (i18n) {
+			const ret = await i18n.loadResource(i18n.locale, ctx, resolvedCmd);
+			if (!ret) console.warn(`Failed to load i18n resources for command: ${name} (${i18n.locale})`);
+		}
+		const localizeDescription = localizable(ctx, resolvedCmd, i18n ? i18n.translate : void 0);
 		const isPositional = hasPositional(resolvedCmd);
-		const commandName = completion$1.addCommand(name, resolvedCmd.description || "", isPositional ? [false] : [], configs?.[name]?.handler || NOOP_HANDLER);
+		const commandName = completion$1.addCommand(name, await localizeDescription(resolveKey("description", ctx)) || resolvedCmd.description || "", isPositional ? [false] : [], toBombshellCompletionHandler(configs?.[name]?.handler || NOOP_HANDLER, i18n ? toLocale(i18n.locale) : void 0));
 		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);
+			completion$1.addOption(commandName, `--${key}`, await localizeDescription(resolveArgKey(key, ctx)) || schema.description || "", toBombshellCompletionHandler(configs[commandName]?.args?.[key]?.handler || NOOP_HANDLER, i18n ? toLocale(i18n.locale) : void 0), schema.short);
 		}
 	}
 }
 function hasPositional(cmd) {
 	return cmd.args && Object.values(cmd.args).some((arg) => arg.type === "positional");
 }
+function toLocale(locale) {
+	return locale instanceof Intl.Locale ? locale : new Intl.Locale(locale);
+}
+function toBombshellCompletionHandler(handler, locale) {
+	return (previousArgs, toComplete, endWithSpace) => handler({
+		previousArgs,
+		toComplete,
+		endWithSpace,
+		locale
+	});
+}
 
 //#endregion
 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.8",
+  "version": "0.27.0-alpha.9",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -52,17 +52,21 @@
     }
   },
   "dependencies": {
-    "@bombsh/tab": "https://pkg.pr.new/bombshell-dev/tab@main",
-    "@gunshi/plugin": "0.27.0-alpha.8"
+    "@gunshi/plugin": "0.27.0-alpha.9"
+  },
+  "peerDependencies": {
+    "@gunshi/plugin-i18n": "0.27.0-alpha.9"
   },
   "devDependencies": {
-    "@types/node": "^22.16.0",
-    "deno": "^2.4.0",
+    "@types/node": "^22.16.5",
+    "deno": "^2.4.2",
     "jsr": "^0.13.5",
     "jsr-exports-lint": "^0.4.1",
     "publint": "^0.3.12",
-    "tsdown": "^0.12.9",
-    "@gunshi/shared": "0.27.0-alpha.8"
+    "rollup-plugin-license": "^3.6.0",
+    "tsdown": "^0.13.0",
+    "@gunshi/plugin-i18n": "0.27.0-alpha.9",
+    "@gunshi/shared": "0.27.0-alpha.9"
   },
   "scripts": {
     "build": "tsdown",