@gunshi/plugin-completion 0.27.0-alpha.9 → 0.27.0-beta.0

package/README.md

@@ -1,9 +1,15 @@
 # @gunshi/plugin-completion
 
+[![Version][npm-version-src]][npm-version-href]
+[![InstallSize][install-size-src]][install-size-src]
+[![JSR][jsr-src]][jsr-href]
+
 > 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.
 
+This completion plugin is powered by [`@bomb.sh/tab`](https://github.com/bombshell-dev/tab)
+
 <!-- eslint-disable markdown/no-missing-label-refs -->
 
 > [!WARNING]
@@ -84,7 +90,7 @@ await cli(process.argv.slice(2), command, {
 
 The plugin automatically adds a `complete` subcommand to your CLI:
 
-```bash
+```sh
 # Generate shell completion script
 my-cli complete bash > ~/.my-cli-completion.bash
 source ~/.my-cli-completion.bash
@@ -101,6 +107,172 @@ The `complete` command accepts the following shell types:
 - `bash` - Bash shell completion
 - `zsh` - Zsh shell completion
 - `fish` - Fish shell completion
+- `powershell` - PowerShell completion
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!NOTE]
+> Supported shells comply with [`@bomb.sh/tab`](https://github.com/bombshell-dev/tab)
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## Shell Completion Setup
+
+This section provides detailed instructions for setting up shell completions in different shells. The setup is a one-time process that enables tab completion for your CLI.
+
+### Prerequisites
+
+Shell completion requires Node.js runtime. Ensure your CLI is running with Node.js (not Deno or Bun).
+
+<!-- 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 -->
+
+### Setup by Shell
+
+#### Bash
+
+Bash users have multiple options for installing completion scripts. Choose the approach that best fits your system:
+
+**Option 1: User-specific completion directory (Recommended)**
+
+```sh
+# Create the completion directory if it doesn't exist
+mkdir -p ~/.local/share/bash-completion/completions
+
+# Generate and install the completion script
+your-cli complete bash > ~/.local/share/bash-completion/completions/your-cli
+
+# Reload your shell configuration
+source ~/.bashrc
+```
+
+**Option 2: Alternative user directory**
+
+```sh
+# Create the completion directory if it doesn't exist
+mkdir -p ~/.bash_completion.d
+
+# Generate and install the completion script
+your-cli complete bash > ~/.bash_completion.d/your-cli
+
+# Add this line to your ~/.bashrc (only needed once)
+echo 'for f in ~/.bash_completion.d/*; do source "$f"; done' >> ~/.bashrc
+
+# Reload your shell configuration
+source ~/.bashrc
+```
+
+#### Zsh
+
+Zsh requires adding the completion directory to your `fpath`:
+
+```sh
+# Create the completion directory if it doesn't exist
+mkdir -p ~/.zsh/completions
+
+# Add the completion directory to fpath in ~/.zshrc (only needed once)
+echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
+echo 'autoload -U compinit && compinit' >> ~/.zshrc
+
+# Generate and install the completion script (note the underscore prefix)
+your-cli complete zsh > ~/.zsh/completions/_your-cli
+
+# Reload your shell configuration
+source ~/.zshrc
+# OR restart the shell
+exec zsh
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!NOTE]
+> Zsh completion files must start with an underscore (`_`) followed by the command name.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+#### Fish
+
+Fish shell has the simplest setup process:
+
+```sh
+# Create the completion directory if it doesn't exist
+mkdir -p ~/.config/fish/completions
+
+# Generate and install the completion script
+your-cli complete fish > ~/.config/fish/completions/your-cli.fish
+
+# Completions are loaded automatically - no reload needed
+# Optionally, restart the shell for immediate effect
+exec fish
+```
+
+#### PowerShell
+
+PowerShell requires adding the completion script to your profile:
+
+```powershell
+# Create the profile directory if it doesn't exist
+New-Item -ItemType Directory -Force -Path (Split-Path $PROFILE)
+
+# Generate the completion script and test it
+your-cli complete powershell | Out-String | Invoke-Expression
+
+# To make it permanent, add it to your PowerShell profile
+your-cli complete powershell >> $PROFILE
+
+# Reload your profile
+. $PROFILE
+# OR restart PowerShell
+```
+
+### Troubleshooting
+
+If completions don't work after setup:
+
+1. **Check script generation**: Ensure `your-cli complete <shell>` outputs a valid script
+2. **Verify file location**: Confirm the completion script is in the correct directory
+3. **Reload shell**: Try opening a new terminal session
+4. **Check permissions**: Ensure the completion file is readable (`chmod +r <file>`)
+5. **Debug mode**: Some shells offer debug options:
+   - Bash: `set -x` before sourcing
+   - Zsh: `setopt xtrace` before sourcing
+   - Fish: `fish --debug=complete`
+   - Powershell: `Set-PSDebug -Trace 1`
+
+### System-wide Installation
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!WARNING]
+> System-wide installation requires root/administrator permissions and is not recommended for most users. User-specific installation is preferred as it doesn't require elevated privileges and is easier to manage.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+If you need system-wide completions:
+
+- **Bash**: `/etc/bash_completion.d/` or `/usr/share/bash-completion/completions/`
+- **Zsh**: `/usr/share/zsh/site-functions/` or `/usr/local/share/zsh/site-functions/`
+- **Fish**: `/usr/share/fish/vendor_completions.d/`
+- **PowerShell**: for Moduele, `/usr/local/share/powershell/Modules/`, for system profiles, `$PSHOME\Profile.ps1`
+
+### Updating Completions
+
+When your CLI updates with new commands or options:
+
+1. Regenerate the completion script: `your-cli complete <shell> > <path-to-completion-file>`
+2. Reload your shell or start a new session
+
+### Uninstalling Completions
+
+To remove completion support:
+
+1. Delete the completion script file
+2. Remove any lines added to your shell configuration files (`.bashrc`, `.zshrc`, etc.)
+3. Reload your shell or start a new session
 
 ### Custom Completion Handlers
 
@@ -186,9 +358,6 @@ interface CompletionConfig {
 
 ```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[]
 
@@ -231,10 +400,18 @@ See the [API References](./docs/index.md)
 
 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
+- [`@bomb.sh/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)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@gunshi/plugin-completion?style=flat
+[npm-version-href]: https://npmjs.com/package/@gunshi/plugin-completion@alpha
+[jsr-src]: https://jsr.io/badges/@gunshi/plugin-completion
+[jsr-href]: https://jsr.io/@gunshi/plugin-completion
+[install-size-src]: https://pkg-size.dev/badge/install/30875

package/lib/index.d.ts

@@ -3,6 +3,7 @@
  * Bombshell related codes are forked from @bombsh/tab
  */
 
+import { Completion } from "@bomb.sh/tab";
 import { PluginWithoutExtension } from "@gunshi/plugin";
 
 //#region ../shared/src/constants.d.ts
@@ -24,18 +25,6 @@ declare const BUILT_IN_KEY_SEPARATOR = ":";
  * 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/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
 /**
@@ -47,28 +36,37 @@ declare const pluginId: GenerateNamespacedKey<'completion', typeof PLUGIN_PREFIX
  */
 type PluginId = typeof pluginId;
 /**
- * Parameters for {@link CompletionHandler | the completion handler}.
+ * Parameters for {@linkcode CompletionHandler | the completion handler}.
  */
 interface CompletionParams {
-  previousArgs: Parameters<Handler>[0];
-  toComplete: Parameters<Handler>[1];
-  endWithSpace: Parameters<Handler>[2];
+  /**
+   * The locale to use for i18n.
+   */
   locale?: Intl.Locale;
 }
 /**
  * The handler for completion.
+ *
+ * @param params - The {@linkcode CompletionParams | parameters} for the completion handler.
+ * @returns An array of {@linkcode Completion | completions}.
  */
-type CompletionHandler = (params: CompletionParams) => ReturnType<Handler>;
+type CompletionHandler = (params: CompletionParams) => Completion[];
 /**
  * Extended command context which provides utilities via completion plugin.
  * These utilities are available via `CommandContext.extensions['g:completion']`.
  */
-interface CompletionCommandContext {}
+interface CompletionExtension {}
 /**
  * Completion configuration, which structure is similar `bombsh/tab`'s `CompletionConfig`.
  */
 interface CompletionConfig {
+  /**
+   * The {@linkcode CompletionHandler | handler} for the completion.
+   */
   handler?: CompletionHandler;
+  /**
+   * The command arguments for the completion.
+   */
   args?: Record<string, {
     handler: CompletionHandler;
   }>;
@@ -77,22 +75,29 @@ interface CompletionConfig {
  * Completion plugin options.
  */
 interface CompletionOptions {
+  /**
+   * The completion configuration
+   */
   config?: {
     /**
-     * The entry point completion configuration.
+     * The entry point {@linkcode CompletionConfig | completion configuration}.
      */
     entry?: CompletionConfig;
     /**
-     * The handlers for subcommands.
+     * The handlers for sub-commands.
      */
     subCommands?: Record<string, CompletionConfig>;
   };
 }
 //#endregion
 //#region src/index.d.ts
+
 /**
- * completion plugin for gunshi
+ * completion plugin
+ *
+ * @param options - A {@linkcode CompletionOptions | Completion options}
+ * @returns A defined plugin as completion
  */
 declare function completion(options?: CompletionOptions): PluginWithoutExtension;
 //#endregion
-export { CompletionCommandContext, CompletionConfig, CompletionHandler, CompletionOptions, CompletionParams, PluginId, completion as default, pluginId };
+export { CompletionConfig, CompletionExtension, CompletionHandler, CompletionOptions, CompletionParams, PluginId, completion as default, pluginId };