mirror of
https://github.com/tiennm99/ccs.git
synced 2026-10-20 02:17:05 +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,332 @@
|
||||
# CCS Error Codes
|
||||
|
||||
Quick reference for CCS error codes and solutions.
|
||||
|
||||
## Error Categories
|
||||
|
||||
- **[E100-E199](#configuration-errors)**: Configuration Errors
|
||||
- **[E200-E299](#profile-management-errors)**: Profile Management Errors
|
||||
- **[E300-E399](#claude-cli-errors)**: Claude CLI Detection Errors
|
||||
- **[E400-E499](#network-api-errors)**: Network/API Errors
|
||||
- **[E500-E599](#file-system-errors)**: File System Errors
|
||||
- **[E900-E999](#internal-errors)**: Internal Errors
|
||||
|
||||
---
|
||||
|
||||
## Configuration Errors
|
||||
|
||||
### E101: Configuration File Missing
|
||||
**Cause**: `~/.ccs/config.json` not found
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Reinstall CCS
|
||||
npm install -g @kaitranntt/ccs --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E102: Invalid JSON in Configuration
|
||||
**Cause**: Corrupted or malformed `config.json`
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Backup and reset
|
||||
mv ~/.ccs/config.json ~/.ccs/config.json.backup
|
||||
npm install -g @kaitranntt/ccs --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E103: Invalid Profile Configuration
|
||||
**Cause**: Profile settings reference non-existent settings file
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check profile settings
|
||||
cat ~/.ccs/config.json
|
||||
|
||||
# Fix path or recreate profile
|
||||
ccs auth create <profile>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Profile Management Errors
|
||||
|
||||
### E104: Profile Not Found
|
||||
**Cause**: Requested profile doesn't exist
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# List available profiles
|
||||
ccs auth list
|
||||
|
||||
# Create new profile
|
||||
ccs auth create <name>
|
||||
|
||||
# Use existing profile
|
||||
ccs <profile> "your prompt"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E105: Profile Already Exists
|
||||
**Cause**: Attempting to create profile that already exists
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Use different name
|
||||
ccs auth create <different-name>
|
||||
|
||||
# Or overwrite existing (use with caution)
|
||||
ccs auth create <name> --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E106: Cannot Delete Default Profile
|
||||
**Cause**: Attempting to remove currently active default profile
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Set different default first
|
||||
ccs auth default <other-profile>
|
||||
|
||||
# Then remove old default
|
||||
ccs auth remove <old-profile>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E107: Invalid Profile Name
|
||||
**Cause**: Profile name contains invalid characters
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Use only: alphanumeric, dash, underscore
|
||||
# Valid: work, test-env, my_profile
|
||||
# Invalid: my profile, test@work, profile!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Claude CLI Errors
|
||||
|
||||
### E301: Claude CLI Not Found
|
||||
**Cause**: Claude CLI not installed or not in PATH
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Install Claude CLI
|
||||
# See: https://docs.claude.com/en/docs/claude-code/installation
|
||||
|
||||
# Verify installation
|
||||
command -v claude # Unix
|
||||
Get-Command claude # Windows
|
||||
|
||||
# Custom path (if installed elsewhere)
|
||||
export CCS_CLAUDE_PATH="/path/to/claude"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E302: Claude CLI Version Incompatible
|
||||
**Cause**: Claude CLI version doesn't meet minimum requirements
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Update Claude CLI
|
||||
# Follow official update guide
|
||||
|
||||
# Check version
|
||||
claude --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E303: Claude CLI Execution Failed
|
||||
**Cause**: Claude CLI failed to start or crashed
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Test Claude directly
|
||||
claude --version
|
||||
|
||||
# Check permissions
|
||||
ls -la $(which claude)
|
||||
|
||||
# Reinstall if needed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Network/API Errors
|
||||
|
||||
### E401: GLMT Proxy Timeout
|
||||
**Cause**: GLMT proxy server failed to start within 30 seconds
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check port conflicts
|
||||
lsof -i :19889 # or random port shown in error
|
||||
|
||||
# Use non-proxy GLM instead
|
||||
ccs glm "your prompt"
|
||||
|
||||
# Enable debug mode
|
||||
export CCS_DEBUG=1
|
||||
ccs glmt "test"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E402: API Key Missing
|
||||
**Cause**: Required API key not configured
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# For GLM/GLMT/Kimi
|
||||
# Add to settings file or use Claude login
|
||||
claude /login
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E403: API Authentication Failed
|
||||
**Cause**: Invalid or expired API credentials
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Re-authenticate
|
||||
claude /login
|
||||
|
||||
# Check API key validity
|
||||
# Verify in Claude dashboard
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E404: API Rate Limit Exceeded
|
||||
**Cause**: Too many requests to API
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Wait and retry
|
||||
sleep 60
|
||||
|
||||
# Check rate limits in API dashboard
|
||||
# Consider upgrading plan
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File System Errors
|
||||
|
||||
### E501: Cannot Create Directory
|
||||
**Cause**: Permission denied or path issues
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Fix ownership
|
||||
sudo chown -R $USER ~/.ccs
|
||||
|
||||
# Fix permissions
|
||||
chmod 755 ~/.ccs
|
||||
|
||||
# Retry
|
||||
npm install -g @kaitranntt/ccs --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E502: Cannot Write File
|
||||
**Cause**: Permission denied writing to CCS directories
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Fix permissions
|
||||
sudo chown -R $USER ~/.ccs ~/.claude
|
||||
chmod -R 755 ~/.ccs ~/.claude
|
||||
|
||||
# Check disk space
|
||||
df -h ~
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E503: Cannot Read File
|
||||
**Cause**: File doesn't exist or permission denied
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check file exists
|
||||
ls -la <file-path-from-error>
|
||||
|
||||
# Fix permissions
|
||||
chmod 644 <file-path>
|
||||
|
||||
# Recreate if missing
|
||||
ccs auth create <profile>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E504: Instance Directory Not Found
|
||||
**Cause**: Profile instance directory missing
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Recreate profile
|
||||
ccs auth remove <profile>
|
||||
ccs auth create <profile>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Internal Errors
|
||||
|
||||
### E900: Internal Error
|
||||
**Cause**: Unexpected error in CCS code
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Report bug with debug output
|
||||
export CCS_DEBUG=1
|
||||
ccs <your-command> 2>&1 | tee error.log
|
||||
|
||||
# Report at: https://github.com/kaitranntt/ccs/issues
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### E901: Invalid State
|
||||
**Cause**: CCS detected inconsistent internal state
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Run health check
|
||||
ccs doctor
|
||||
|
||||
# Reset CCS data (backup first!)
|
||||
mv ~/.ccs ~/.ccs.backup
|
||||
npm install -g @kaitranntt/ccs --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter an error not listed here:
|
||||
|
||||
1. Enable debug mode: `export CCS_DEBUG=1`
|
||||
2. Run the failing command
|
||||
3. Check logs: `~/.ccs/logs/`
|
||||
4. Report issue: https://github.com/kaitranntt/ccs/issues
|
||||
|
||||
Include:
|
||||
- Error code
|
||||
- Full error message
|
||||
- Debug output
|
||||
- OS/platform info
|
||||
- CCS version: `ccs --version`
|
||||
Reference in new issue
Block a user