@kaitranntt/ccs 7.65.3 → 7.66.0-dev.2

package/scripts/completion/README.md

@@ -2,14 +2,16 @@
 
 Tab completion for CCS commands, subcommands, profiles, and flags.
 
+The completion scripts are thin adapters over the hidden `ccs __complete` backend so
+all supported shells stay aligned with the same command graph.
+
 **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
+- Complete root commands, help topics, provider shortcuts, and command flags
+- Complete `ccs auth` and `ccs api` lifecycle subcommands
 - Context-aware: suggests relevant options based on current command
 
 ## Quick Install (Recommended)
@@ -32,6 +34,12 @@ ccs --shell-completion --fish        # Force fish
 ccs --shell-completion --powershell  # Force PowerShell
 ```
 
+**Help and verification:**
+```bash
+ccs help completion
+ccs --shell-completion --force
+```
+
 ## Manual Installation
 
 Completion files are installed to `~/.ccs/completions/` during `npm install`.
@@ -116,188 +124,104 @@ sudo cp scripts/completion/ccs.fish /usr/share/fish/vendor_completions.d/
 
 ```bash
 $ ccs <TAB>
-auth      doctor    glm       kimi      work      personal  --help    --version
+auth      api       cliproxy  config    doctor    docker    help
 
-$ ccs auth <TAB>
-create    list      show      remove    default   --help
+$ ccs help <TAB>
+profiles  providers  completion  targets
 ```
 
-### Profile Completion
+### Context Completion
 
 ```bash
 $ ccs auth show <TAB>
 work      personal  team      --json
 
-$ ccs auth remove <TAB>
-work      personal  team      --yes     -y
+$ ccs api <TAB>
+create    list      discover  copy    export  import  remove
 ```
 
-### Flag Completion
+### Backend Contract
 
 ```bash
-$ ccs auth list <TAB>
---verbose --json
-
-$ ccs auth show work <TAB>
---json
+$ ccs __complete --shell bash --current do
+doctor
+docker
 ```
 
-## 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)
+Shell adapters now call the shared CCS completion backend instead of maintaining their own
+copy of the command graph. That means:
+- top-level commands, help topics, and provider shortcuts come from CCS itself
+- dynamic profiles and CLIProxy variants resolve through the real config loaders
+- bash, zsh, fish, and PowerShell stay aligned with the same completion logic
 
 ## 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
-   ```
+### Bash
 
-3. Check if completion is loaded:
+1. Check if completion is loaded:
    ```bash
    complete -p ccs
    ```
-
-   Should output:
-   ```
-   complete -F _ccs_completion ccs
+2. Verify the backend directly:
+   ```bash
+   ccs __complete --shell bash --current "" -- help
    ```
 
-### Zsh: Completion not working
+### Zsh
 
-1. Verify completion system is enabled in `~/.zshrc`:
+1. Verify completion system is enabled:
    ```zsh
    autoload -Uz compinit && compinit
    ```
-
-2. Check if completion is loaded:
+2. Rebuild the cache if needed:
    ```zsh
-   which _ccs
+   rm ~/.zcompdump && compinit
    ```
-
-3. Rebuild completion cache:
+3. Verify the backend directly:
    ```zsh
-   rm ~/.zcompdump && compinit
+   ccs __complete --shell zsh --current "" -- help
    ```
 
-### PowerShell: Completion not working
-
-1. Check PowerShell version (5.1+ required):
-   ```powershell
-   $PSVersionTable.PSVersion
-   ```
+### PowerShell
 
-2. Verify profile is loaded:
+1. Check that the profile exists:
    ```powershell
    Test-Path $PROFILE
    ```
-
-3. Check if completion is registered:
+2. Verify the backend directly:
    ```powershell
-   (Get-ArgumentCompleter).CommandName | Select-String ccs
+   ccs __complete --shell powershell --current "" -- help
    ```
 
-### Fish: Completion not working
-
-1. Check Fish version (3.0+ required):
-   ```fish
-   fish --version
-   ```
+### Fish
 
-2. Verify completion file is in the right location:
+1. Verify completion file location:
    ```fish
    ls ~/.config/fish/completions/ccs.fish
    ```
-
-3. Verify jq is installed (required for profile completion):
-   ```fish
-   which jq
-   ```
-
-4. Test completion manually:
+2. Test completion manually:
    ```fish
    complete -C'ccs '
    ```
-
-5. If needed, rebuild completions:
+3. Verify the backend directly:
    ```fish
-   fish_update_completions
+   ccs __complete --shell fish --current "" -- help
    ```
 
 ## 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
+- Bash uses `complete -F`
+- Zsh uses a custom `_ccs` completion function
+- Fish uses `complete -a` with backend command substitution
+- PowerShell uses `Register-ArgumentCompleter`
+- All four shells now delegate suggestion logic to `ccs __complete`
 
 ## 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
+When adding or changing command surfaces:
+1. Update the shared TypeScript command/completion catalog
+2. Run `bun run validate`
+3. Smoke-check at least one installed shell adapter plus the backend directly
 
 ## See Also
 

package/scripts/completion/ccs.bash

@@ -1,210 +1,42 @@
 # 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
+  local cur
   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 config doctor env persist 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
+  local tokens_before_current=()
+  if [[ ${COMP_CWORD} -gt 1 ]]; then
+    tokens_before_current=("${COMP_WORDS[@]:1:COMP_CWORD-1}")
   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
+  while IFS= read -r line; do
+    [[ -n "${line}" ]] && COMPREPLY+=("${line}")
+  done < <(__ccs_completion_run "${cur}" "${tokens_before_current[@]}")
 
-  # 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
+  return 0
+}
 
-  # env subcommands
-  if [[ ${COMP_WORDS[1]} == "env" ]]; then
-    case "${prev}" in
-      env)
-        # Complete with profile names and flags (inline profiles since $cliproxy_profiles is out of scope)
-        local env_opts="--format --shell --ide --help -h gemini codex agy qwen iflow kiro ghcp claude default"
-        if [[ -f ~/.ccs/config.json ]]; then
-          env_opts="$env_opts $(jq -r '.profiles | keys[]' ~/.ccs/config.json 2>/dev/null || true)"
-        fi
-        if [[ -f ~/.ccs/profiles.json ]]; then
-          env_opts="$env_opts $(jq -r '.profiles | keys[]' ~/.ccs/profiles.json 2>/dev/null || true)"
-        fi
-        COMPREPLY=( $(compgen -W "${env_opts}" -- ${cur}) )
-        return 0
-        ;;
-      --format)
-        COMPREPLY=( $(compgen -W "openai anthropic raw claude-extension" -- ${cur}) )
-        return 0
-        ;;
-      --shell)
-        COMPREPLY=( $(compgen -W "auto bash zsh fish powershell" -- ${cur}) )
-        return 0
-        ;;
-      --ide)
-        COMPREPLY=( $(compgen -W "vscode cursor windsurf" -- ${cur}) )
-        return 0
-        ;;
-      *)
-        COMPREPLY=( $(compgen -W "--format --shell --ide --help -h" -- ${cur}) )
-        return 0
-        ;;
-    esac
-  fi
+__ccs_completion_run() {
+  local current="$1"
+  shift || true
 
-  # Flags for doctor command
-  if [[ ${COMP_WORDS[1]} == "doctor" ]]; then
-    COMPREPLY=( $(compgen -W "--help -h" -- ${cur}) )
-    return 0
+  local script_dir repo_root repo_cli
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  repo_root="$(cd "${script_dir}/../.." && pwd)"
+  repo_cli="${repo_root}/dist/ccs.js"
+  if [[ ! -f "${repo_cli}" ]]; then
+    repo_cli="${repo_root}/bin/ccs.js"
   fi
-
-  # Flags for update command
-  if [[ ${COMP_WORDS[1]} == "update" ]]; then
-    COMPREPLY=( $(compgen -W "--force --beta --dev --help -h" -- ${cur}) )
+  if [[ -f "${repo_cli}" ]]; then
+    node "${repo_cli}" __complete --shell bash --current "${current}" -- "$@" 2>/dev/null
     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
+  if command -v ccs >/dev/null 2>&1; then
+    ccs __complete --shell bash --current "${current}" -- "$@" 2>/dev/null
   fi
-
-  return 0
 }
 
-# Register completion function
 complete -F _ccs_completion ccs