@kaitranntt/ccs 3.4.6 → 4.1.0

package/scripts/completion/README.md

@@ -0,0 +1,308 @@
+# Shell Completion for CCS
+
+Tab completion for CCS commands, subcommands, profiles, and flags.
+
+**Supported Shells:** Bash, Zsh, Fish, PowerShell
+
+## Features
+
+- Complete profile names (both settings-based and account-based)
+- Complete `ccs auth` subcommands (create, list, show, remove, default)
+- Complete flags (`--help`, `--version`, `--json`, `--verbose`, `--yes`)
+- Complete profile names for auth subcommands
+- Context-aware: suggests relevant options based on current command
+
+## Quick Install (Recommended)
+
+```bash
+ccs --shell-completion
+```
+
+This will:
+- Auto-detect your shell
+- Copy completion files to `~/.ccs/completions/`
+- Configure your shell profile with proper comment markers
+- Show instructions to activate
+
+**Manual shell selection:**
+```bash
+ccs --shell-completion --bash        # Force bash
+ccs --shell-completion --zsh         # Force zsh
+ccs --shell-completion --fish        # Force fish
+ccs --shell-completion --powershell  # Force PowerShell
+```
+
+## Manual Installation
+
+Completion files are installed to `~/.ccs/completions/` during `npm install`.
+
+### Bash
+
+Add to `~/.bashrc` or `~/.bash_profile`:
+
+```bash
+# CCS shell completion
+source ~/.ccs/completions/ccs.bash
+```
+
+Then reload:
+```bash
+source ~/.bashrc
+```
+
+### Zsh
+
+1. Create completion directory:
+   ```zsh
+   mkdir -p ~/.zsh/completion
+   ```
+
+2. Copy completion file:
+   ```zsh
+   cp ~/.ccs/completions/ccs.zsh ~/.zsh/completion/_ccs
+   ```
+
+3. Add to `~/.zshrc`:
+   ```zsh
+   # CCS shell completion
+   fpath=(~/.zsh/completion $fpath)
+   autoload -Uz compinit && compinit
+   ```
+
+4. Reload:
+   ```zsh
+   source ~/.zshrc
+   ```
+
+### PowerShell
+
+Add to your PowerShell profile (`$PROFILE`):
+
+```powershell
+# CCS shell completion
+. "$HOME\.ccs\completions\ccs.ps1"
+```
+
+Then reload:
+```powershell
+. $PROFILE
+```
+
+### Fish
+
+**User installation (recommended)**
+
+Fish automatically loads completions from `~/.config/fish/completions/`:
+
+```fish
+# Create completion directory if it doesn't exist
+mkdir -p ~/.config/fish/completions
+
+# Copy completion script
+cp scripts/completion/ccs.fish ~/.config/fish/completions/
+```
+
+That's it! Fish will automatically load the completion on demand. No need to source or reload.
+
+**System-wide installation (requires sudo)**
+
+```fish
+sudo cp scripts/completion/ccs.fish /usr/share/fish/vendor_completions.d/
+```
+
+## Usage Examples
+
+### Basic Completion
+
+```bash
+$ ccs <TAB>
+auth      doctor    glm       glmt      kimi      work      personal  --help    --version
+
+$ ccs auth <TAB>
+create    list      show      remove    default   --help
+```
+
+### Profile Completion
+
+```bash
+$ ccs auth show <TAB>
+work      personal  team      --json
+
+$ ccs auth remove <TAB>
+work      personal  team      --yes     -y
+```
+
+### Flag Completion
+
+```bash
+$ ccs auth list <TAB>
+--verbose --json
+
+$ ccs auth show work <TAB>
+--json
+```
+
+## Completion Behavior
+
+### Top-level (after `ccs`)
+- Built-in commands: `auth`, `doctor`
+- Flags: `--help`, `--version`, `-h`, `-v`
+- Settings-based profiles: from `~/.ccs/config.json`
+- Account-based profiles: from `~/.ccs/profiles.json`
+
+### After `ccs auth`
+- Subcommands: `create`, `list`, `show`, `remove`, `default`
+- Flags: `--help`, `-h`
+
+### After `ccs auth <subcommand>`
+- **create**: No completion (user enters new profile name)
+  - Flags: `--force`
+- **list**: No profile completion
+  - Flags: `--verbose`, `--json`
+- **show**: Account profiles only
+  - Flags: `--json`
+- **remove**: Account profiles only
+  - Flags: `--yes`, `-y`
+- **default**: Account profiles only
+
+### After `ccs <profile>`
+- No completion (Claude CLI arguments are free-form)
+
+## Troubleshooting
+
+### Bash: Completion not working
+
+1. Check if bash-completion is installed:
+   ```bash
+   # macOS
+   brew install bash-completion
+
+   # Ubuntu/Debian
+   sudo apt install bash-completion
+   ```
+
+2. Verify jq is installed (required for profile completion):
+   ```bash
+   command -v jq
+   ```
+
+3. Check if completion is loaded:
+   ```bash
+   complete -p ccs
+   ```
+
+   Should output:
+   ```
+   complete -F _ccs_completion ccs
+   ```
+
+### Zsh: Completion not working
+
+1. Verify completion system is enabled in `~/.zshrc`:
+   ```zsh
+   autoload -Uz compinit && compinit
+   ```
+
+2. Check if completion is loaded:
+   ```zsh
+   which _ccs
+   ```
+
+3. Rebuild completion cache:
+   ```zsh
+   rm ~/.zcompdump && compinit
+   ```
+
+### PowerShell: Completion not working
+
+1. Check PowerShell version (5.1+ required):
+   ```powershell
+   $PSVersionTable.PSVersion
+   ```
+
+2. Verify profile is loaded:
+   ```powershell
+   Test-Path $PROFILE
+   ```
+
+3. Check if completion is registered:
+   ```powershell
+   (Get-ArgumentCompleter).CommandName | Select-String ccs
+   ```
+
+### Fish: Completion not working
+
+1. Check Fish version (3.0+ required):
+   ```fish
+   fish --version
+   ```
+
+2. Verify completion file is in the right location:
+   ```fish
+   ls ~/.config/fish/completions/ccs.fish
+   ```
+
+3. Verify jq is installed (required for profile completion):
+   ```fish
+   which jq
+   ```
+
+4. Test completion manually:
+   ```fish
+   complete -C'ccs '
+   ```
+
+5. If needed, rebuild completions:
+   ```fish
+   fish_update_completions
+   ```
+
+## Technical Details
+
+### Bash Implementation
+- Uses `complete -F` for programmable completion
+- Compatible with bash 3.2+ (macOS default)
+- Reads profiles dynamically using `jq`
+- Context-aware based on `COMP_CWORD` and `COMP_WORDS`
+
+### Zsh Implementation
+- Uses `_arguments` and `_describe` for rich completion
+- Compatible with zsh 5.0+
+- Supports completion descriptions
+- Context-aware using `$state` and `$words`
+
+### PowerShell Implementation
+- Uses `Register-ArgumentCompleter`
+- Compatible with PowerShell 5.1+
+- Reads profiles dynamically using `ConvertFrom-Json`
+- Provides `CompletionResult` objects
+
+### Fish Implementation
+- Uses declarative `complete` command
+- Compatible with Fish 3.0+
+- Automatic loading from `~/.config/fish/completions/`
+- Helper functions for dynamic profile loading
+- Context-aware using `__fish_seen_subcommand_from`
+- No manual sourcing required
+
+## Dependencies
+
+- **jq**: Required for reading profiles from JSON files
+  - Install: `brew install jq` (macOS) or `apt install jq` (Ubuntu)
+  - Already required by CCS core functionality
+
+## Contributing
+
+When adding new commands or flags:
+1. Update all four completion scripts (bash, zsh, fish, PowerShell)
+2. Test on each shell
+3. Update this README with new completion examples
+4. Maintain cross-shell parity
+
+## See Also
+
+- [CCS Documentation](https://github.com/kaitranntt/ccs)
+- [Bash Programmable Completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html)
+- [Zsh Completion System](http://zsh.sourceforge.net/Doc/Release/Completion-System.html)
+- [Fish Completion Tutorial](https://fishshell.com/docs/current/completions.html)
+- [PowerShell Argument Completers](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/register-argumentcompleter)

package/scripts/completion/ccs.bash

@@ -0,0 +1,81 @@
+# Bash completion for CCS (Claude Code Switch)
+# Compatible with bash 3.2+
+#
+# Installation:
+#   Add to ~/.bashrc or ~/.bash_profile:
+#     source /path/to/ccs/scripts/completion/ccs.bash
+#
+#   Or install system-wide (requires sudo):
+#     sudo cp scripts/completion/ccs.bash /etc/bash_completion.d/ccs
+
+_ccs_completion() {
+  local cur prev words cword
+  COMPREPLY=()
+
+  # Get current word and previous word
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+  # Top-level completion (first argument)
+  if [[ ${COMP_CWORD} -eq 1 ]]; then
+    local commands="auth doctor"
+    local flags="--help --version -h -v"
+    local profiles=""
+
+    # Add profiles from config.json (settings-based profiles)
+    if [[ -f ~/.ccs/config.json ]]; then
+      profiles="$profiles $(jq -r '.profiles | keys[]' ~/.ccs/config.json 2>/dev/null || true)"
+    fi
+
+    # Add profiles from profiles.json (account-based profiles)
+    if [[ -f ~/.ccs/profiles.json ]]; then
+      profiles="$profiles $(jq -r '.profiles | keys[]' ~/.ccs/profiles.json 2>/dev/null || true)"
+    fi
+
+    # Combine all options
+    local opts="$commands $flags $profiles"
+    COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+    return 0
+  fi
+
+  # auth subcommands
+  if [[ ${prev} == "auth" ]]; then
+    local auth_commands="create list show remove default --help -h"
+    COMPREPLY=( $(compgen -W "${auth_commands}" -- ${cur}) )
+    return 0
+  fi
+
+  # Completion for auth subcommands that need profile names
+  if [[ ${COMP_WORDS[1]} == "auth" ]]; then
+    case "${prev}" in
+      show|remove|default)
+        # Complete with account profile names only
+        if [[ -f ~/.ccs/profiles.json ]]; then
+          local profiles=$(jq -r '.profiles | keys[]' ~/.ccs/profiles.json 2>/dev/null || true)
+          COMPREPLY=( $(compgen -W "${profiles}" -- ${cur}) )
+        fi
+        return 0
+        ;;
+      create)
+        # No completion for create (user enters new name)
+        return 0
+        ;;
+      list)
+        # Complete with list flags
+        COMPREPLY=( $(compgen -W "--verbose --json" -- ${cur}) )
+        return 0
+        ;;
+    esac
+  fi
+
+  # Flags for doctor command
+  if [[ ${COMP_WORDS[1]} == "doctor" ]]; then
+    COMPREPLY=( $(compgen -W "--help -h" -- ${cur}) )
+    return 0
+  fi
+
+  return 0
+}
+
+# Register completion function
+complete -F _ccs_completion ccs

package/scripts/completion/ccs.fish

@@ -0,0 +1,92 @@
+# Fish completion for CCS (Claude Code Switch)
+# Compatible with fish 3.0+
+#
+# Installation:
+#   Copy to ~/.config/fish/completions/:
+#     mkdir -p ~/.config/fish/completions
+#     cp scripts/completion/ccs.fish ~/.config/fish/completions/
+#
+#   Fish will automatically load completions from this directory.
+#   No need to source or reload - completions are loaded on demand.
+
+# Helper function to get profiles
+function __fish_ccs_get_profiles
+    set -l config_path ~/.ccs/config.json
+    set -l profiles_path ~/.ccs/profiles.json
+
+    # Get settings-based profiles from config.json
+    if test -f $config_path
+        jq -r '.profiles | keys[]' $config_path 2>/dev/null
+    end
+
+    # Get account-based profiles from profiles.json
+    if test -f $profiles_path
+        jq -r '.profiles | keys[]' $profiles_path 2>/dev/null
+    end
+end
+
+# Helper function to get account profiles only
+function __fish_ccs_get_account_profiles
+    set -l profiles_path ~/.ccs/profiles.json
+
+    if test -f $profiles_path
+        jq -r '.profiles | keys[]' $profiles_path 2>/dev/null
+    end
+end
+
+# Helper function to check if we're in auth context
+function __fish_ccs_using_auth
+    __fish_seen_subcommand_from auth
+end
+
+# Helper function to check specific auth subcommand
+function __fish_ccs_using_auth_subcommand
+    set -l subcommand $argv[1]
+    __fish_ccs_using_auth; and __fish_seen_subcommand_from $subcommand
+end
+
+# Disable file completion for ccs
+complete -c ccs -f
+
+# Top-level flags
+complete -c ccs -s h -l help -d 'Show help message'
+complete -c ccs -s v -l version -d 'Show version information'
+
+# Top-level commands
+complete -c ccs -n 'not __fish_seen_subcommand_from auth doctor' -a 'auth' -d 'Manage multiple Claude accounts'
+complete -c ccs -n 'not __fish_seen_subcommand_from auth doctor' -a 'doctor' -d 'Run health check and diagnostics'
+
+# Top-level profile completion (all profiles)
+complete -c ccs -n 'not __fish_seen_subcommand_from auth doctor' -a '(__fish_ccs_get_profiles)' -d 'Switch to profile'
+
+# auth subcommands
+complete -c ccs -n '__fish_ccs_using_auth; and not __fish_seen_subcommand_from create list show remove default' -a 'create' -d 'Create new profile and login'
+complete -c ccs -n '__fish_ccs_using_auth; and not __fish_seen_subcommand_from create list show remove default' -a 'list' -d 'List all saved profiles'
+complete -c ccs -n '__fish_ccs_using_auth; and not __fish_seen_subcommand_from create list show remove default' -a 'show' -d 'Show profile details'
+complete -c ccs -n '__fish_ccs_using_auth; and not __fish_seen_subcommand_from create list show remove default' -a 'remove' -d 'Remove saved profile'
+complete -c ccs -n '__fish_ccs_using_auth; and not __fish_seen_subcommand_from create list show remove default' -a 'default' -d 'Set default profile'
+
+# auth command flags
+complete -c ccs -n '__fish_ccs_using_auth' -s h -l help -d 'Show help for auth commands'
+
+# auth create flags
+complete -c ccs -n '__fish_ccs_using_auth_subcommand create' -l force -d 'Allow overwriting existing profile'
+
+# auth list flags
+complete -c ccs -n '__fish_ccs_using_auth_subcommand list' -l verbose -d 'Show additional details'
+complete -c ccs -n '__fish_ccs_using_auth_subcommand list' -l json -d 'Output in JSON format'
+
+# auth show - profile names and flags
+complete -c ccs -n '__fish_ccs_using_auth_subcommand show' -a '(__fish_ccs_get_account_profiles)' -d 'Account profile'
+complete -c ccs -n '__fish_ccs_using_auth_subcommand show' -l json -d 'Output in JSON format'
+
+# auth remove - profile names and flags
+complete -c ccs -n '__fish_ccs_using_auth_subcommand remove' -a '(__fish_ccs_get_account_profiles)' -d 'Account profile'
+complete -c ccs -n '__fish_ccs_using_auth_subcommand remove' -l yes -d 'Skip confirmation prompts'
+complete -c ccs -n '__fish_ccs_using_auth_subcommand remove' -s y -d 'Skip confirmation prompts'
+
+# auth default - profile names only
+complete -c ccs -n '__fish_ccs_using_auth_subcommand default' -a '(__fish_ccs_get_account_profiles)' -d 'Account profile'
+
+# doctor command flags
+complete -c ccs -n '__fish_seen_subcommand_from doctor' -s h -l help -d 'Show help for doctor command'

package/scripts/completion/ccs.ps1

@@ -0,0 +1,157 @@
+# PowerShell completion for CCS (Claude Code Switch)
+# Compatible with PowerShell 5.1+
+#
+# Installation:
+#   Add to your PowerShell profile ($PROFILE):
+#     . /path/to/ccs/scripts/completion/ccs.ps1
+#
+#   Or install for current user:
+#     Copy-Item scripts/completion/ccs.ps1 ~\Documents\PowerShell\Scripts\
+#     Add to profile: . ~\Documents\PowerShell\Scripts\ccs.ps1
+
+Register-ArgumentCompleter -CommandName ccs -ScriptBlock {
+    param($commandName, $wordToComplete, $commandAst, $fakeBoundParameters)
+
+    $commands = @('auth', 'doctor', '--help', '--version', '-h', '-v')
+    $authCommands = @('create', 'list', 'show', 'remove', 'default', '--help', '-h')
+    $listFlags = @('--verbose', '--json')
+    $removeFlags = @('--yes', '-y')
+    $showFlags = @('--json')
+
+    # Get current position in command
+    $words = $commandAst.ToString() -split '\s+' | Where-Object { $_ -ne '' }
+    $position = $words.Count
+
+    # Helper function to get profiles
+    function Get-CcsProfiles {
+        param([string]$Type = 'all')
+
+        $profiles = @()
+
+        # Settings-based profiles
+        if ($Type -in @('all', 'settings')) {
+            $configPath = "$env:USERPROFILE\.ccs\config.json"
+            if (Test-Path $configPath) {
+                try {
+                    $config = Get-Content $configPath -Raw | ConvertFrom-Json
+                    $profiles += $config.profiles.PSObject.Properties.Name
+                } catch {}
+            }
+        }
+
+        # Account-based profiles
+        if ($Type -in @('all', 'account')) {
+            $profilesPath = "$env:USERPROFILE\.ccs\profiles.json"
+            if (Test-Path $profilesPath) {
+                try {
+                    $data = Get-Content $profilesPath -Raw | ConvertFrom-Json
+                    $profiles += $data.profiles.PSObject.Properties.Name
+                } catch {}
+            }
+        }
+
+        return $profiles | Sort-Object -Unique
+    }
+
+    # Top-level completion
+    if ($position -eq 2) {
+        $allOptions = $commands + (Get-CcsProfiles)
+        $allOptions | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+            [System.Management.Automation.CompletionResult]::new(
+                $_,
+                $_,
+                'ParameterValue',
+                $_
+            )
+        }
+        return
+    }
+
+    # auth subcommand completion
+    if ($words[1] -eq 'auth') {
+        if ($position -eq 3) {
+            # auth subcommands
+            $authCommands | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                [System.Management.Automation.CompletionResult]::new(
+                    $_,
+                    $_,
+                    'ParameterValue',
+                    $_
+                )
+            }
+        } elseif ($position -eq 4) {
+            # Profile names or flags for auth subcommands
+            switch ($words[2]) {
+                'show' {
+                    $options = (Get-CcsProfiles -Type account) + $showFlags
+                    $options | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                        [System.Management.Automation.CompletionResult]::new(
+                            $_,
+                            $_,
+                            'ParameterValue',
+                            $_
+                        )
+                    }
+                }
+                'remove' {
+                    $options = (Get-CcsProfiles -Type account) + $removeFlags
+                    $options | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                        [System.Management.Automation.CompletionResult]::new(
+                            $_,
+                            $_,
+                            'ParameterValue',
+                            $_
+                        )
+                    }
+                }
+                'default' {
+                    Get-CcsProfiles -Type account | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                        [System.Management.Automation.CompletionResult]::new(
+                            $_,
+                            $_,
+                            'ParameterValue',
+                            $_
+                        )
+                    }
+                }
+                'list' {
+                    $listFlags | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                        [System.Management.Automation.CompletionResult]::new(
+                            $_,
+                            $_,
+                            'ParameterValue',
+                            $_
+                        )
+                    }
+                }
+                'create' {
+                    # No completion for create (user types new name)
+                }
+            }
+        } elseif ($position -eq 5) {
+            # Flags after profile name
+            switch ($words[2]) {
+                'show' {
+                    $showFlags | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                        [System.Management.Automation.CompletionResult]::new(
+                            $_,
+                            $_,
+                            'ParameterValue',
+                            $_
+                        )
+                    }
+                }
+                'remove' {
+                    $removeFlags | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                        [System.Management.Automation.CompletionResult]::new(
+                            $_,
+                            $_,
+                            'ParameterValue',
+                            $_
+                        )
+                    }
+                }
+            }
+        }
+    }
+}