mirror of
https://github.com/tiennm99/ccs.git
synced 2026-10-13 14:15:56 +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:
kaitrannttandClaude Code committed
1 parent
7bd2e9e4ba
commit
e9eb215d1f
24 files changed
+2392
-484
No files matched your search
@@ -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
|
||||
@@ -0,0 +1,101 @@
|
||||
# Version Management
|
||||
|
||||
## Overview
|
||||
|
||||
CCS uses a centralized version management system to ensure consistency across all components.
|
||||
|
||||
## Version Locations
|
||||
|
||||
The version number must be kept in sync across these files:
|
||||
|
||||
1. **`VERSION`** - Primary version file (read by ccs/ccs.ps1 at runtime)
|
||||
2. **`installers/install.sh`** - Hardcoded for standalone installations (`curl | bash`)
|
||||
3. **`installers/install.ps1`** - Hardcoded for standalone installations (`irm | iex`)
|
||||
|
||||
## Why Hardcoded Versions in Installers?
|
||||
|
||||
When users run:
|
||||
- `curl -fsSL ccs.kaitran.ca/install | bash`
|
||||
- `irm ccs.kaitran.ca/install.ps1 | iex`
|
||||
|
||||
The installer script is downloaded and executed directly **without** the VERSION file. Therefore, installers must have a hardcoded version as fallback.
|
||||
|
||||
For git-based installations, the VERSION file is read if available, overriding the hardcoded version.
|
||||
|
||||
## Updating Version
|
||||
|
||||
### Automated Method (Recommended)
|
||||
|
||||
Use the provided script to bump the version automatically:
|
||||
|
||||
```bash
|
||||
# Bump patch version (2.1.1 -> 2.1.2)
|
||||
./scripts/bump-version.sh patch
|
||||
|
||||
# Bump minor version (2.1.1 -> 2.2.0)
|
||||
./scripts/bump-version.sh minor
|
||||
|
||||
# Bump major version (2.1.1 -> 3.0.0)
|
||||
./scripts/bump-version.sh major
|
||||
```
|
||||
|
||||
This updates:
|
||||
- VERSION file
|
||||
- installers/install.sh (hardcoded version)
|
||||
- installers/install.ps1 (hardcoded version)
|
||||
- Creates git tag (if in git repo)
|
||||
|
||||
### Manual Method
|
||||
|
||||
If updating manually, update version in ALL three locations:
|
||||
|
||||
1. **VERSION file**:
|
||||
```bash
|
||||
echo "2.1.2" > VERSION
|
||||
```
|
||||
|
||||
2. **installers/install.sh** (line ~34):
|
||||
```bash
|
||||
CCS_VERSION="2.1.2"
|
||||
```
|
||||
|
||||
3. **installers/install.ps1** (line ~33):
|
||||
```powershell
|
||||
$CcsVersion = "2.1.2"
|
||||
```
|
||||
|
||||
## Release Checklist
|
||||
|
||||
When releasing a new version:
|
||||
|
||||
- [ ] Update version using `./scripts/update-version.sh X.Y.Z`
|
||||
- [ ] Review changes: `git diff`
|
||||
- [ ] Update CHANGELOG.md with release notes
|
||||
- [ ] Commit changes: `git commit -am "chore: bump version to X.Y.Z"`
|
||||
- [ ] Create tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
|
||||
- [ ] Push: `git push && git push --tags`
|
||||
- [ ] Verify CloudFlare worker serves updated installer
|
||||
|
||||
## Version Display
|
||||
|
||||
After installation, users can check version:
|
||||
|
||||
```bash
|
||||
# Shows CCS version (from VERSION file if available)
|
||||
ccs --version
|
||||
|
||||
# Shows Claude CLI version
|
||||
ccs version
|
||||
```
|
||||
|
||||
## Semantic Versioning
|
||||
|
||||
CCS follows [Semantic Versioning](https://semver.org/):
|
||||
|
||||
- **MAJOR** (X.0.0): Breaking changes
|
||||
- **MINOR** (0.X.0): New features (backward compatible)
|
||||
- **PATCH** (0.0.X): Bug fixes
|
||||
|
||||
Current version: **2.1.1**
|
||||
- 2.1.0: Added task delegation feature
|
||||
- 2.1.1: Fixed argument parsing bug (flags treated as profiles)
|
||||
Reference in new issue
Block a user