mirror of
https://github.com/tiennm99/ccs.git
synced 2026-10-18 02:14:25 +00:00
feat(cli): comprehensive UX improvements for v3.5.0 (#7)
Implements 6-phase CLI UX improvement plan with comprehensive error handling, interactive features, and cross-platform consistency. ### Added - Shell auto-completion (bash, zsh, PowerShell, Fish) - Error codes (E101-E901) with documentation URLs - Fuzzy matching "Did you mean?" suggestions (Levenshtein distance) - Progress indicators (doctor [n/9] counter, GLMT proxy spinner) - Interactive confirmation prompts with --yes/-y automation flag - JSON output format (--json) for auth commands - Impact display (session count, paths) before destructive operations - Comprehensive test suite (15 tests, 100% pass rate) - Complete error documentation in docs/errors/ - Cross-platform `--shell-completion` command ### Changed - Error boxes: Unicode (╔═╗) → ASCII (===) for compatibility - JSON output uses CCS version instead of schema version - Help text includes EXAMPLES section across platforms - Test suite properly counts test cases (not assertions) ### Fixed - --yes flag bug (returned false instead of true) - Help text consistency (added Uninstall section to bash) - Test pass rate calculation (excludes skipped tests) - Help section comparison (locale-specific sort) ### Testing - 13/13 tests passing (2 legitimately skipped) - Cross-platform verified (Node.js, bash, PowerShell) - All error codes documented and tested
This commit is contained in:
Kai (Tam Nhu) Tran authored and GitHub committed
1 parent
01cff1114b
commit
f40e9647ec
30 files changed
+4231
-105
No files matched your search
@@ -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)
|
||||
Reference in new issue
Block a user