mirror of
https://github.com/tiennm99/ccs.git
synced 2026-08-20 02:27:45 +00:00
fix(core): add VERSION file handling and comprehensive test coverage
This commit fixes version management and argument parsing issues across both Windows and Linux/macOS platforms, achieving 100% test coverage. Changes: - Add VERSION file installation to both installers (install.sh, install.ps1) - Fix version/help command detection when using 'powershell -File' syntax - Rename PowerShell param from $Profile to $ProfileOrFlag for clarity - Add $FirstArg detection to check both ProfileOrFlag and RemainingArgs - Create comprehensive edge case test suites for both platforms: * tests/edge-cases.ps1 - 31 tests for Windows (100% pass) * tests/edge-cases.sh - 37 tests for Linux/macOS (100% pass) - Fix multiline regex matching in tests for error messages - Update test expectations to match platform-specific behavior - Reorganize project structure: * Move installers to installers/ directory * Add scripts/ directory for version management * Add config/ directory for configuration templates * Add docs/ directory for documentation Test Results: - Windows (PowerShell): 31/31 tests passing (100%) - Linux/macOS (Bash): 37/37 tests passing (100%) Breaking Changes: None - Installers moved but GitHub URLs updated in README files - All existing functionality preserved Co-authored-by: Claude Code <claude@anthropic.com>
This commit is contained in:
kaitranntt
co-authored by
Claude Code
Claude Code
parent
7bd2e9e4ba
commit
e9eb215d1f
@@ -0,0 +1,191 @@
|
||||
# CCS Workflow Documentation
|
||||
|
||||
Workflow documentation for CCS v2.0.0 covering installation, runtime behavior, and troubleshooting.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
User Command: ccs [profile] [claude-args...]
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ ccs (wrapper) │ ← Bash (Unix) or PowerShell (Windows)
|
||||
└────────┬────────┘
|
||||
│
|
||||
├─ 1. Read ~/.ccs/config.json
|
||||
├─ 2. Lookup profile → settings file
|
||||
├─ 3. Validate settings file exists
|
||||
│
|
||||
▼
|
||||
┌────────────────┐
|
||||
│ Profile System │
|
||||
└───────┬────────┘
|
||||
│
|
||||
├─ default: ~/.claude/settings.json
|
||||
└─ glm: ~/.ccs/glm.settings.json
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ Claude CLI │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **ccs wrapper**: Lightweight script (bash/PowerShell)
|
||||
2. **Config file**: `~/.ccs/config.json` (profile → settings mappings)
|
||||
3. **Settings files**: Claude CLI settings JSON format
|
||||
4. **Claude CLI**: Official Anthropic CLI (unchanged)
|
||||
|
||||
### Design Principles
|
||||
|
||||
- **YAGNI**: Only 2 profiles (default/glm)
|
||||
- **KISS**: Simple delegation, no magic
|
||||
- **DRY**: One source of truth (config.json)
|
||||
- **Non-invasive**: Never modifies ~/.claude/settings.json
|
||||
|
||||
---
|
||||
|
||||
## Installation Workflow
|
||||
|
||||
### Process
|
||||
|
||||
1. **Create directories**: `~/.ccs/`, `~/.local/bin/`
|
||||
2. **Install executables**:
|
||||
- Git mode: Symlink from repo
|
||||
- Standalone: Download from GitHub
|
||||
3. **Install .claude folder**: Commands and skills
|
||||
4. **Create config**: `config.json` if missing
|
||||
5. **Create GLM profile**: `glm.settings.json` if missing
|
||||
6. **Backup**: Single `config.json.backup` (overwrites)
|
||||
7. **Validate**: Check JSON syntax
|
||||
|
||||
### Files Created
|
||||
|
||||
```
|
||||
~/.ccs/
|
||||
├── ccs # Main executable
|
||||
├── config.json # Profile mappings
|
||||
├── config.json.backup # Single backup (no timestamp)
|
||||
├── glm.settings.json # GLM profile
|
||||
├── uninstall.sh # Uninstaller
|
||||
└── .claude/ # Claude Code integration
|
||||
├── commands/ccs.md
|
||||
└── skills/ccs-delegation/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Runtime Workflow
|
||||
|
||||
### Unix/Linux/macOS
|
||||
|
||||
```
|
||||
ccs [profile] [args]
|
||||
↓
|
||||
Read config.json
|
||||
↓
|
||||
Lookup profile → settings file path
|
||||
↓
|
||||
Validate file exists
|
||||
↓
|
||||
exec claude --settings <path> [args]
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```
|
||||
ccs [profile] [args]
|
||||
↓
|
||||
Read config.json
|
||||
↓
|
||||
Lookup profile → settings file path
|
||||
↓
|
||||
Validate file exists
|
||||
↓
|
||||
exec claude --settings <path> [args]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Profile System
|
||||
|
||||
### Config Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"glm": "~/.ccs/glm.settings.json",
|
||||
"default": "~/.claude/settings.json"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Settings File Format
|
||||
|
||||
**GLM Profile** (`~/.ccs/glm.settings.json`):
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
|
||||
"ANTHROPIC_AUTH_TOKEN": "your_api_key",
|
||||
"ANTHROPIC_MODEL": "glm-4.6",
|
||||
"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.6",
|
||||
"ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
|
||||
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.6"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Claude (Default)** (`~/.claude/settings.json`):
|
||||
- User-managed, CCS never modifies it
|
||||
- Referenced by default profile
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Profile Not Found
|
||||
|
||||
| Check | Fix |
|
||||
|-------|-----|
|
||||
| config.json exists? | Run installer |
|
||||
| Valid JSON? | Fix syntax or restore from backup |
|
||||
| Profile in config? | Add profile or use default/glm |
|
||||
| Settings file exists? | Create from template |
|
||||
|
||||
### PowerShell Crash (Windows)
|
||||
|
||||
**Error**: `SetEnvironmentVariable` error
|
||||
|
||||
**Fix**:
|
||||
1. Check settings format has `{"env": {...}}`
|
||||
2. Ensure all values are strings (not booleans/objects)
|
||||
3. Remove non-env fields from settings file
|
||||
|
||||
### Installation Issues
|
||||
|
||||
| Issue | Fix |
|
||||
|-------|-----|
|
||||
| 404 Not Found | Check installers exist in GitHub |
|
||||
| Permission denied | Check ~/.ccs/ permissions |
|
||||
| jq not found | Install jq: `brew install jq` (Unix) |
|
||||
| PATH warning | Add `~/.local/bin` to PATH |
|
||||
|
||||
---
|
||||
|
||||
## Key Points
|
||||
|
||||
1. **Installation**: Creates 2 profiles (glm + default), validates JSON
|
||||
2. **Runtime**: Simple delegation to Claude CLI via `--settings` flag
|
||||
3. **Cross-platform**: Identical behavior on Unix/Linux/macOS/Windows
|
||||
4. **Non-invasive**: Never touches `~/.claude/settings.json`
|
||||
5. **Validation**: JSON syntax checking prevents errors
|
||||
6. **Backup**: Single file, overwrites each install
|
||||
|
||||
---
|
||||
|
||||
**Version**: v2.0.0
|
||||
**Updated**: 2025-11-02
|
||||
Reference in New Issue
Block a user