@jonnyhoo/ccs 1.0.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,176 @@
+# 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 api cliproxy doctor sync update"
+    local flags="--help --version --shell-completion -h -v -sc"
+    local cliproxy_profiles="gemini codex agy qwen"
+    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
+
+    # Add cliproxy variants from config.json
+    if [[ -f ~/.ccs/config.json ]]; then
+      profiles="$profiles $(jq -r '.cliproxy | keys[]' ~/.ccs/config.json 2>/dev/null || true)"
+    fi
+
+    # Combine all options
+    local opts="$commands $flags $cliproxy_profiles $profiles"
+    COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+    return 0
+  fi
+
+  # CLIProxy provider flags (gemini, codex, agy, qwen)
+  if [[ ${COMP_WORDS[1]} =~ ^(gemini|codex|agy|qwen)$ ]]; then
+    local provider_flags="--auth --config --logout --headless --help -h"
+    COMPREPLY=( $(compgen -W "${provider_flags}" -- ${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
+
+  # api subcommands
+  if [[ ${prev} == "api" ]]; then
+    local api_commands="create list remove --help -h"
+    COMPREPLY=( $(compgen -W "${api_commands}" -- ${cur}) )
+    return 0
+  fi
+
+  # cliproxy subcommands
+  if [[ ${prev} == "cliproxy" ]]; then
+    local cliproxy_commands="create list remove --install --latest --help -h"
+    COMPREPLY=( $(compgen -W "${cliproxy_commands}" -- ${cur}) )
+    return 0
+  fi
+
+  # Completion for cliproxy subcommands
+  if [[ ${COMP_WORDS[1]} == "cliproxy" ]]; then
+    case "${prev}" in
+      remove|delete|rm)
+        # Complete with cliproxy variant names
+        if [[ -f ~/.ccs/config.json ]]; then
+          local variants=$(jq -r '.cliproxy | keys[]' ~/.ccs/config.json 2>/dev/null || true)
+          COMPREPLY=( $(compgen -W "${variants}" -- ${cur}) )
+        fi
+        return 0
+        ;;
+      create)
+        # Complete with create flags
+        COMPREPLY=( $(compgen -W "--provider --model --force --yes -y" -- ${cur}) )
+        return 0
+        ;;
+      --provider)
+        # Complete with provider names
+        COMPREPLY=( $(compgen -W "gemini codex agy qwen" -- ${cur}) )
+        return 0
+        ;;
+      list|ls)
+        # No flags for list
+        return 0
+        ;;
+      --install)
+        # User enters version number
+        return 0
+        ;;
+    esac
+  fi
+
+  # Completion for api subcommands
+  if [[ ${COMP_WORDS[1]} == "api" ]]; then
+    case "${prev}" in
+      remove|delete|rm)
+        # Complete with settings profile names
+        if [[ -f ~/.ccs/config.json ]]; then
+          local profiles=$(jq -r '.profiles | keys[]' ~/.ccs/config.json 2>/dev/null || true)
+          COMPREPLY=( $(compgen -W "${profiles}" -- ${cur}) )
+        fi
+        return 0
+        ;;
+      create)
+        # Complete with create flags
+        COMPREPLY=( $(compgen -W "--base-url --api-key --model --force --yes -y" -- ${cur}) )
+        return 0
+        ;;
+      list)
+        # No flags for list
+        return 0
+        ;;
+    esac
+  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)
+        # Complete with create flags
+        COMPREPLY=( $(compgen -W "--force" -- ${cur}) )
+        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
+
+  # Flags for update command
+  if [[ ${COMP_WORDS[1]} == "update" ]]; then
+    COMPREPLY=( $(compgen -W "--force --beta --dev --help -h" -- ${cur}) )
+    return 0
+  fi
+
+  # Flags for shell-completion command
+  if [[ ${prev} == "--shell-completion" || ${prev} == "-sc" ]]; then
+    COMPREPLY=( $(compgen -W "--bash --zsh --fish --powershell" -- ${cur}) )
+    return 0
+  fi
+
+  return 0
+}
+
+# Register completion function
+complete -F _ccs_completion ccs