From 64925d57ca69a839b7066a0e761f6f7f31b65205 Mon Sep 17 00:00:00 2001 From: kaitranntt Date: Wed, 5 Nov 2025 10:16:18 -0500 Subject: [PATCH] checkpoint: before test restructure migration --- CLAUDE.md | 51 ++- README.md | 2 + README.vi.md | 43 ++- bin/config-manager.js | 12 +- docs/installation.md | 11 + docs/troubleshooting.md | 40 +++ docs/vi/development-workflow.vi.md | 300 +++++++++++++++++ docs/vi/installation.vi.md | 38 ++- docs/vi/project-roadmap.vi.md | 506 +++++++++++++++++++++++++++++ docs/vi/testing-requirements.vi.md | 380 ++++++++++++++++++++++ docs/vi/version-management.vi.md | 99 ++++++ package.json | 4 +- scripts/postinstall.js | 99 ++++++ tests/edge-cases.sh | 45 +++ 14 files changed, 1607 insertions(+), 23 deletions(-) create mode 100644 docs/vi/development-workflow.vi.md create mode 100644 docs/vi/project-roadmap.vi.md create mode 100644 docs/vi/testing-requirements.vi.md create mode 100644 docs/vi/version-management.vi.md create mode 100755 scripts/postinstall.js diff --git a/CLAUDE.md b/CLAUDE.md index 39bf2af7..fe993f30 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,6 +34,7 @@ The tool does ONE thing: map profile names to Claude settings files. Never add f ## Architecture +**Core Flow** (common to both npm and traditional install): ``` User: ccs [profile] [claude-args] ↓ @@ -43,33 +44,61 @@ Lookup profile → settings file path ↓ Validate settings file exists ↓ -exec claude --settings [args] +Execute: claude --settings [args] ``` +**Implementation Variants**: +- **npm package**: Pure Node.js (bin/ccs.js) using child_process.spawn +- **Traditional install**: Platform-specific bash (lib/ccs) or PowerShell (lib/ccs.ps1) + **Key Files**: -- `package.json`: npm package manifest with bin field configuration +- `package.json`: npm package manifest with bin field configuration and postinstall script - `bin/ccs.js`: Cross-platform Node.js entry point (npm package) +- `scripts/postinstall.js`: Auto-creates config files during npm install (idempotent) - `lib/ccs` (bash) / `lib/ccs.ps1` (PowerShell): Platform-specific executable wrappers - `installers/install.sh` / `installers/install.ps1`: Traditional installation scripts - `installers/uninstall.sh` / `installers/uninstall.ps1`: Removal scripts - `VERSION`: Single source of truth for version (format: MAJOR.MINOR.PATCH) - `.claude/`: Commands and skills for Claude Code integration -**npm Package Architecture**: +**npm Package Architecture** (Pure Node.js): ``` +npm install -g @kaitranntt/ccs + ↓ +npm runs postinstall: scripts/postinstall.js + ├─ Create ~/.ccs/ directory + ├─ Create config.json (if missing) + └─ Create glm.settings.json (if missing) + ↓ +npm creates ccs command (symlink to bin/ccs.js) + ↓ User: ccs [profile] [claude-args] ↓ -npm creates bin/ccs.js symlink/wrapper +bin/ccs.js (pure Node.js, cross-platform): + ├─ Parse arguments and detect profile + ├─ Read ~/.ccs/config.json (via config-manager.js) + ├─ Get settings path for profile + ├─ Detect claude CLI location (via claude-detector.js) + └─ spawn('claude', ['--settings', settingsPath, ...args]) +``` + +**Traditional Installer Architecture** (Bash/PowerShell): +``` +curl -fsSL ccs.kaitran.ca/install | bash # or irm install | iex ↓ -bin/ccs.js detects platform (Unix vs Windows) - ├─ Unix: spawn bash lib/ccs [args] - └─ Windows: spawn pwsh/powershell lib/ccs.ps1 [args] +installers/install.sh (or install.ps1) + ├─ Create ~/.ccs/ directory + ├─ Copy lib/ccs (or lib/ccs.ps1) + ├─ Create config.json + ├─ Create glm.settings.json + └─ Create symlink ~/.local/bin/ccs → ~/.ccs/ccs ↓ -Read ~/.ccs/config.json +User: ccs [profile] [claude-args] ↓ -Lookup profile → settings file path - ↓ -exec claude --settings [args] +lib/ccs (bash) or lib/ccs.ps1 (PowerShell): + ├─ Read ~/.ccs/config.json (jq or ConvertFrom-Json) + ├─ Get settings path for profile + └─ exec claude --settings [args] ``` **Installation Creates**: diff --git a/README.md b/README.md index 3808385a..ea4e827b 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,8 @@ bun add -g @kaitranntt/ccs ### Configuration (Auto-created) +**CCS automatically creates configuration during installation** (via npm postinstall script). + **~/.ccs/config.json**: ```json { diff --git a/README.vi.md b/README.vi.md index a22c6ae5..d653fed2 100644 --- a/README.vi.md +++ b/README.vi.md @@ -30,6 +30,17 @@ claude /login ### Phương Pháp Cài Đặt Chính +#### Option 1: npm Package (Được khuyến nghị) + +**macOS / Linux / Windows** +```bash +npm install -g @kaitranntt/ccs +``` + +Tương thích với các trình quản lý package npm, yarn, pnpm, và bun. + +#### Option 2: Cài Đặt Trực Tiếp (Truyền thống) + **macOS / Linux** ```bash curl -fsSL ccs.kaitran.ca/install | bash @@ -55,8 +66,28 @@ ccs "Debug issue này" ccs "Viết unit tests" ``` +#### Package Manager Options + +Tất cả các trình quản lý package chính đều được hỗ trợ: + +```bash +# npm (mặc định) +npm install -g @kaitranntt/ccs + +# yarn +yarn global add @kaitranntt/ccs + +# pnpm (ít hơn 70% dung lượng đĩa) +pnpm add -g @kaitranntt/ccs + +# bun (nhanh hơn 30x) +bun add -g @kaitranntt/ccs +``` + ### Cấu Hình (Tự Tạo) +**CCS tự động tạo cấu hình trong quá trình cài đặt** (thông qua script postinstall của npm). + **~/.ccs/config.json**: ```json { @@ -228,17 +259,17 @@ irm ccs.kaitran.ca/uninstall | iex ## 📖 Tài Liệu **Tài liệu đầy đủ trong [docs/](./docs/)**: -- [Hướng dẫn Cài đặt](./docs/vi/installation.vi.md) -- [Cấu hình](./docs/vi/configuration.vi.md) -- [Ví dụ Sử dụng](./docs/vi/usage.vi.md) -- [Khắc phục Sự cố](./docs/vi/troubleshooting.vi.md) -- [Đóng góp](./docs/vi/contributing.vi.md) +- [Hướng dẫn Cài đặt](./docs/installation.md) +- [Cấu hình](./docs/configuration.md) +- [Ví dụ Sử dụng](./docs/usage.md) +- [Khắc phục Sự cố](./docs/troubleshooting.md) +- [Đóng góp](./docs/contributing.md) --- ## 🤝 Đóng Góp -Chúng tôi chào mừng đóng góp! Xem [Hướng dẫn Đóng góp](./docs/contributing.md) để biết chi tiết. +Chúng tôi chào mừng đóng góp! Vui lòng xem [Hướng dẫn Đóng góp](./docs/contributing.md) để biết chi tiết. --- diff --git a/bin/config-manager.js b/bin/config-manager.js index 8fd62d9d..88549e2f 100644 --- a/bin/config-manager.js +++ b/bin/config-manager.js @@ -20,10 +20,13 @@ function readConfig() { showError(`Config file not found: ${configPath} Solutions: - 1. Reinstall CCS: + 1. Reinstall CCS (auto-creates config): + npm install -g @kaitranntt/ccs --force + + 2. Or use traditional installer: ${isWindows ? 'irm ccs.kaitran.ca/install | iex' : 'curl -fsSL ccs.kaitran.ca/install | bash'} - 2. Or create config manually: + 3. Or create manually: mkdir -p ~/.ccs cat > ~/.ccs/config.json << 'EOF' { @@ -32,7 +35,10 @@ Solutions: "default": "~/.claude/settings.json" } } -EOF`); +EOF + + Note: If you installed with npm --ignore-scripts, configs weren't created. + Reinstall without that flag: npm install -g @kaitranntt/ccs --force`); process.exit(1); } diff --git a/docs/installation.md b/docs/installation.md index c819dcff..b1c78baf 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -18,11 +18,22 @@ npm install -g @kaitranntt/ccs **Benefits of npm installation:** - ✅ Cross-platform compatibility - ✅ Automatic PATH configuration +- ✅ Auto-creates config files via postinstall script - ✅ Easy updates: `npm update -g @kaitranntt/ccs` - ✅ Clean uninstall: `npm uninstall -g @kaitranntt/ccs` - ✅ Version pinning support - ✅ Dependency management +**What Happens During Install:** +1. npm downloads and installs the package +2. Postinstall script automatically creates `~/.ccs/config.json` and `~/.ccs/glm.settings.json` +3. npm creates `ccs` command in your PATH + +**Note**: If you use `npm install --ignore-scripts`, config files won't be created. Run without that flag: +```bash +npm install -g @kaitranntt/ccs --force +``` + ## One-Liner Installation (Traditional) ### macOS / Linux diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 44bbfefc..5e74dcac 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,5 +1,45 @@ # CCS Troubleshooting Guide +## npm Installation Issues + +### Config File Not Found After npm Install + +**Symptom**: After `npm install -g @kaitranntt/ccs`, running `ccs --version` shows error: +``` +Config file not found: /home/user/.ccs/config.json +``` + +**Cause**: You may have installed with `--ignore-scripts` flag, which skips the postinstall script that creates config files. + +**Solution**: +```bash +# Reinstall without --ignore-scripts +npm install -g @kaitranntt/ccs --force + +# Or manually run postinstall +node $(npm root -g)/@kaitranntt/ccs/scripts/postinstall.js + +# Or use traditional installer +curl -fsSL ccs.kaitran.ca/install | bash # macOS/Linux +irm ccs.kaitran.ca/install | iex # Windows +``` + +**Verify**: +```bash +ls -la ~/.ccs/ +# Should show: config.json, glm.settings.json +``` + +### Check npm ignore-scripts Setting + +```bash +# Check if ignore-scripts is enabled +npm config get ignore-scripts + +# If true, disable it (or use --force on install) +npm config set ignore-scripts false +``` + ## Windows-Specific Issues ### PowerShell Execution Policy diff --git a/docs/vi/development-workflow.vi.md b/docs/vi/development-workflow.vi.md new file mode 100644 index 00000000..4f7fae3f --- /dev/null +++ b/docs/vi/development-workflow.vi.md @@ -0,0 +1,300 @@ +# Tài Liệu Workflow CCS + +Tài liệu workflow cho CCS v2.0.0 bao gồm cài đặt, hành vi runtime, và khắc phục sự cố. + +--- + +## Tổng Quan Kiến Trúc + +``` +User Command: ccs [profile] [claude-args...] + │ + ▼ +┌─────────────────┐ +│ ccs (wrapper) │ ← Bash (Unix) hoặc PowerShell (Windows) +└────────┬────────┘ + │ + ├─ 1. Đọc ~/.ccs/config.json + ├─ 2. Tìm profile → file settings + ├─ 3. Xác nhận file settings tồn tại + │ + ▼ + ┌────────────────┐ + │ Profile System │ + └───────┬────────┘ + │ + ├─ default: ~/.claude/settings.json + └─ glm: ~/.ccs/glm.settings.json + │ + ▼ + ┌──────────────────┐ + │ Claude CLI │ + └──────────────────┘ +``` + +### Các Thành Phần Chính + +1. **ccs wrapper**: Script nhẹ (bash/PowerShell) +2. **Config file**: `~/.ccs/config.json` (profile → settings mappings) +3. **Settings files**: Định dạng JSON settings Claude CLI +4. **Claude CLI**: CLI chính thức của Anthropic (không thay đổi) + +### Nguyên Tắc Thiết Kế + +- **YAGNI**: Chỉ có 2 profiles (default/glm) +- **KISS**: Delegation đơn giản, không magic +- **DRY**: Một nguồn chân lý duy nhất (config.json) +- **Non-invasive**: Không bao giờ sửa ~/.claude/settings.json + +--- + +## Workflow Cài Đặt + +### Quy Trình + +1. **Phát hiện Nền tảng**: Windows so với Unix +2. **Tạo thư mục**: `~/.ccs/`, `~/.local/bin` +3. **Dọn dẹp cài đặt cũ**: Xóa các cài đặt `/usr/local/bin` cũ (nếu là symlinks CCS) +4. **Cài đặt executables**: + - Git mode: Symlink từ repo + - Standalone: Tải xuống từ GitHub +5. **Cài đặt thư mục .claude**: Commands và skills +6. **Tạo config**: `config.json` nếu thiếu +7. **Tạo profile GLM**: `glm.settings.json` nếu thiếu +8. **Backup**: File `config.json.backup` duy nhất (ghi đè) +9. **Xác nhận**: Kiểm tra cú pháp JSON +10. **Cấu hình PATH**: Tự động phát hiện shell, thêm vào profile +11. **Hiển thị hướng dẫn**: Tải lại shell, API key GLM (nếu cần) + +### Vị Trí Cài Đặt Thống Nhất (v2.2.0+) + +**Tất cả Hệ Thống Unix**: `~/.local/bin/ccs` +- Người dùng có thể ghi, không cần sudo +- Cấu hình PATH tự động cho bash, zsh, fish +- Thiết lập idempotent (an toàn khi chạy nhiều lần) + +**Windows**: `%USERPROFILE%\.ccs\ccs.ps1` +- Tự động thêm vào PATH người dùng + +### Quản Lý Shell Profile + +**Tự động phát hiện** (`detect_shell_profile()`): +- Trích xuất shell từ biến `$SHELL` +- Trả về file profile phù hợp: + - bash: `~/.bashrc` (Linux) hoặc `~/.bash_profile` (macOS) + - zsh: `~/.zshrc` + - fish: `~/.config/fish/config.fish` +- Xác thực tên shell (chỉ chữ và số) +- Mặc định là `~/.bashrc` nếu không xác định được + +**Kiểm tra PATH** (`check_path_configured()`): +- Kiểm tra nếu `~/.local/bin` trong `$PATH` hiện tại +- Trả về true nếu đã được cấu hình + +**Thêm PATH** (`add_to_path()`): +- Tạo file profile nếu thiếu +- Kiểm tra comment marker CCS hiện có +- Thêm export PATH phù hợp cho shell: + - bash/zsh: `export PATH="$HOME/.local/bin:$PATH"` + - fish: `set -gx PATH $HOME/.local/bin $PATH` +- Idempotent: bỏ qua nếu đã thêm + +**Workflow cấu hình** (`configure_shell_path()`): +- Kiểm tra nếu PATH đã được cấu hình +- Phát hiện shell profile +- Thêm entry PATH +- Hiển thị hướng dẫn tải lại +- Fallback sang hướng dẫn thủ công nếu thất bại + +### Các Tệp Được Tạo + +**Vị Trí Executable**: +- macOS / Linux: `~/.local/bin/ccs` (symlink đến `~/.ccs/ccs`) +- Windows: `%USERPROFILE%\.ccs\ccs.ps1` + +**Thư Mục Cấu Hình** (`~/.ccs/`): +``` +~/.ccs/ +├── ccs # Tệp thực thi chính (symlink target) +├── config.json # Profile mappings +├── config.json.backup # Backup duy nhất (không timestamp) +├── glm.settings.json # Profile GLM +├── VERSION # Tệp phiên bản +├── uninstall.sh # Uninstaller +└── .claude/ # Tích hợp Claude Code + ├── commands/ccs.md + └── skills/ccs-delegation/ +``` + +--- + +## Workflow Runtime + +### Unix/Linux/macOS + +``` +ccs [profile] [args] + ↓ +Đọc config.json + ↓ +Tìm profile → đường dẫn file settings + ↓ +Xác nhận file tồn tại + ↓ +exec claude --settings [args] +``` + +### Windows + +``` +ccs [profile] [args] + ↓ +Đọc config.json + ↓ +Tìm profile → đường dẫn file settings + ↓ +Xác nhận file tồn tại + ↓ +exec claude --settings [args] +``` + +--- + +## Hệ Thống Profile + +### Cấu Trúc Config + +```json +{ + "profiles": { + "glm": "~/.ccs/glm.settings.json", + "default": "~/.claude/settings.json" + } +} +``` + +### Định Dạng File Settings + +**Profile GLM** (`~/.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`): +- Người dùng quản lý, CCS không bao giờ sửa nó +- Được tham chiếu bởi profile default + +--- + +## Khắc Phục Sự Cố + +### Profile Không Tìm Thấy + +| Kiểm Tra | Sửa | +|----------|-----| +| config.json tồn tại? | Chạy installer | +| JSON hợp lệ? | Sửa cú pháp hoặc phục hồi từ backup | +| Profile trong config? | Thêm profile hoặc dùng default/glm | +| File settings tồn tại? | Tạo từ template | + +### Lỗi PowerShell (Windows) + +**Lỗi**: Lỗi `SetEnvironmentVariable` + +**Sửa**: +1. Kiểm tra định dạng settings có `{"env": {...}}` +2. Đảm bảo tất cả giá trị là chuỗi (không phải boolean/objects) +3. Xóa các trường không thuộc env khỏi file settings + +### Vấn Đề Cài Đặt + +| Vấn Đề | Sửa | +|---------|-----| +| 404 Not Found | Kiểm tra installers tồn tại trong GitHub | +| Permission denied | Kiểm tra quyền ~/.ccs/ | +| jq không tìm thấy | Cài đặt jq: `brew install jq` (Unix) | +| Cảnh báo PATH | Thêm `~/.local/bin` vào PATH | + +--- + +## Tiêu Chuẩn Output Terminal + +### Các Hàm Màu + +**Phát Hiện TTY**: Màu chỉ hiển thị khi output ra terminal (không pipe/redirect) +```bash +if [[ -t 2 ]] && [[ -z "${NO_COLOR:-}" ]]; then + # Bật màu +else + # Tắt màu +fi +``` + +**Hỗ Trợ NO_COLOR**: Tôn trọng biến môi trường `NO_COLOR` +```bash +export NO_COLOR=1 # Vô hiệu hóa tất cả output màu +``` + +### Các Loại Message + +**Error Messages** (đỏ, trong khung): +``` +╔═════════════════════════════════════════════╗ +║ ERROR ║ +╚═════════════════════════════════════════════╝ +``` + +**Critical Messages** (đỏ, trong khung, "ACTION REQUIRED"): +``` +╔═════════════════════════════════════════════╗ +║ ACTION REQUIRED ║ +╚═════════════════════════════════════════════╝ +``` + +**Warning Messages** (vàng): +``` +[!] WARNING +``` + +**Success Messages** (xanh lá): +``` +[OK] Success message +``` + +**Info Messages** (thường): +``` +[i] Information +``` + +### Ký Tự ASCII (Không Emojis) + +Tất cả output sử dụng ký tự ASCII để tương thích: +- `[OK]` - Thành công +- `[!]` - Cảnh báo +- `[X]` - Lỗi/Thất bại +- `[i]` - Thông tin + +## Các Điểm Chính + +1. **Cài Đặt**: Vị trí thống nhất (`~/.local/bin`), cấu hình PATH tự động, xác nhận JSON +2. **Runtime**: Delegation đơn giản đến Claude CLI qua flag `--settings` +3. **Đa nền tảng**: Vị trí Unix thống nhất, hành vi giống hệt nhau +4. **Non-invasive**: Không bao giờ chạm `~/.claude/settings.json` +5. **Xác nhận**: Kiểm tra cú pháp JSON ngăn chặn lỗi +6. **Backup**: File duy nhất, ghi đè mỗi lần cài +7. **Output Terminal**: Phát hiện TTY, hỗ trợ NO_COLOR, chỉ ký tự ASCII +8. **Hỗ Trợ Shell**: Tự động phát hiện bash, zsh, fish + +--- + +**Phiên bản**: v2.2.0 +**Cập nhật**: 2025-11-03 \ No newline at end of file diff --git a/docs/vi/installation.vi.md b/docs/vi/installation.vi.md index cfc3ef5d..8502c3e4 100644 --- a/docs/vi/installation.vi.md +++ b/docs/vi/installation.vi.md @@ -1,6 +1,40 @@ # Hướng Dẫn Cài Đặt CCS -## Cài Đặt Một Dòng Lệnh (Khuyến Nghị) +## Cài Đặt npm Package (Được khuyến nghị) + +### Cài Đặt Đa Nền Tảng + +**macOS / Linux / Windows** +```bash +npm install -g @kaitranntt/ccs +``` + +**Tương thích với tất cả các trình quản lý package:** +- `npm install -g @kaitranntt/ccs` +- `yarn global add @kaitranntt/ccs` +- `pnpm add -g @kaitranntt/ccs` +- `bun add -g @kaitranntt/ccs` + +**Lợi ích của việc cài đặt npm:** +- ✅ Tương thích đa nền tảng +- ✅ Cấu hình PATH tự động +- ✅ Tự động tạo file cấu hình qua script postinstall +- ✅ Cập nhật dễ dàng: `npm update -g @kaitranntt/ccs` +- ✅ Gỡ cài đặt sạch: `npm uninstall -g @kaitranntt/ccs` +- ✅ Hỗ trợ version pinning +- ✅ Quản lý dependencies + +**Những Gì Xảy Ra Trong Quá Trình Cài Đặt:** +1. npm tải xuống và cài đặt package +2. Script postinstall tự động tạo `~/.ccs/config.json` và `~/.ccs/glm.settings.json` +3. npm tạo lệnh `ccs` trong PATH của bạn + +**Lưu ý**: Nếu bạn dùng `npm install --ignore-scripts`, file cấu hình sẽ không được tạo. Chạy lại mà không có flag đó: +```bash +npm install -g @kaitranntt/ccs --force +``` + +## Cài Đặt Một Dòng Lệnh (Truyền thống) ### macOS / Linux @@ -183,7 +217,7 @@ echo 'set -gx PATH $HOME/.local/bin $PATH' >> ~/.config/fish/config.fish - PowerShell 5.1+ (đã cài sẵn trên Windows 10+) - [Claude CLI](https://docs.claude.com/en/docs/claude-code/installation) -### Cài đặt jq (chỉ macOS / Linux) +### Cài đặt jq (macOS / Linux, tùy chọn) ```bash # macOS diff --git a/docs/vi/project-roadmap.vi.md b/docs/vi/project-roadmap.vi.md new file mode 100644 index 00000000..0193e1d4 --- /dev/null +++ b/docs/vi/project-roadmap.vi.md @@ -0,0 +1,506 @@ +# Lộ Trình Dự Án CCS + +**Dự án:** CCS (Claude Code Switch) +**Phiên bản:** 2.3.0 (Nâng cao PowerShell 7+ & Node.js) +**Cập nhật lần cuối:** 2025-11-04 +**Trạng thái:** Sẵn sàng Sản xuất với Hỗ Trợ Đa Nền Tảng Nâng Cao + +--- + +## Tổng Quan Dự Án + +CCS là một wrapper CLI nhẹ để chuyển đổi tức thì giữa các mô hình AI Claude Sonnet 4.5 và GLM 4.6. Xây dựng với nguyên tắc YAGNI/KISS/DRY, CCS cung cấp chuyển đổi mô hình liền mạch mà không cần sửa các file settings Claude. + +**Giá trị cốt lõi:** Một lệnh, không downtime, đúng model cho từng tác vụ. + +--- + +## Các Giai Đoạn Phát Triển + +### Giai đoạn 1: Nền tảng (HOÀN THÀNH - Q4 2025) ✅ + +**Trạng thái:** 100% Hoàn thành +**Timeline:** 31 Tháng 10 - 1 Tháng 11, 2025 +**Phiên bản:** 1.0.0 - 1.1.0 + +**Thành tựu:** +- ✅ Chuyển đổi dựa trên profile giữa Claude và GLM +- ✅ Hỗ trợ đa nền tảng (macOS, Linux, Windows) +- ✅ Cài đặt một dòng qua curl/irm +- ✅ Tự động phát hiện provider hiện tại +- ✅ Hỗ trợ git worktree và submodule +- ✅ Nâng cao profile GLM với biến model mặc định + +**Chỉ số chính:** +- Tỷ lệ thành công cài đặt: 100% +- Nền tảng được hỗ trợ: 3 (macOS, Linux, Windows) +- Dependencies: jq (tùy chọn), Claude CLI + +--- + +### Giai đoạn 2: Đơn giản hóa & Ổn định (HOÀN THÀNH - Tháng 11, 2025) ✅ + +**Trạng thái:** 100% Hoàn thành +**Timeline:** 2 Tháng 11, 2025 +**Phiên bản:** 2.0.0 - 2.1.3 + +**Thay đổi lớn:** + +#### v2.0.0 - Đơn giản hóa Kiến trúc +- ✅ **BREAKING:** Xóa profile `ccs son` (dùng `ccs` cho Claude subscription) +- ✅ Cấu trúc config đơn giản hóa (chỉ có glm fallback) +- ✅ Cách tiếp cận non-invasive (không bao giờ sửa ~/.claude/settings.json) +- ✅ Installer thông minh với xác nhận và tự sửa chữa +- ✅ Phát hiện migration và tự nâng cấp từ v1.x +- ✅ Backup config với timestamp +- ✅ File VERSION để quản lý phiên bản tập trung +- ✅ Workflow GitHub Actions cho triển khai CloudFlare Worker + +**Sửa lỗi quan trọng:** +- ✅ Lỗi env var PowerShell (lọc nghiêm ngặt ngăn các giá trị không phải chuỗi) +- ✅ Xác nhận JSON cho tất cả file config +- ✅ Thông báo lỗi tốt hơn với giải pháp có thể hành động + +#### v2.1.0 - Tính nhất quán Windows +- ✅ Windows PowerShell dùng flag `--settings` (giống như Unix) +- ✅ Xóa 64 dòng quản lý env var (giảm 27% code) +- ✅ Cách tiếp cận đa nền tảng giống hệt nhau (macOS/Linux/Windows) + +#### v2.1.1 - Nâng cao Hỗ trợ Windows +- ✅ Cờ `--version` và `--help` hoạt động đúng +- ✅ Cải thiện phân tích đối số (xử lý cờ trước profile) + +#### v2.1.2 - Sửa Cài đặt +- ✅ Sửa lỗi 404 trong các cài đặt độc lập +- ✅ Sửa đường dẫn URL GitHub raw (vị trí uninstall.sh) +- ✅ 68/68 tests passed (tỷ lệ pass 100%) +- ✅ Zero lỗ hổng bảo mật + +#### v2.1.3 - Tài liệu & Đáng tin cậy +- ✅ Cập nhật tài liệu toàn diện +- ✅ Nâng cao xử lý lỗi +- ✅ Tái cấu trúc README để rõ ràng hơn + +**Chỉ số chính:** +- Giảm code: 27% trong phiên bản PowerShell +- Độ bao phủ test: 100% pass rate (68 tests) +- Lỗ hổng bảo mật: 0 +- Thành công cài đặt: 100% + +--- + +### Giai đoạn 3: Nâng cao Trải nghiệm Người dùng (HOÀN THÀNH - Tháng 11, 2025) ✅ + +**Trạng thái:** 100% Hoàn thành +**Timeline:** 2-4 Tháng 11, 2025 +**Phiên bản:** 2.1.4 (Phát hành) + 2.2.0 (npm Package) + +**Tính năng hoàn thành:** + +#### Cải tiến Output Terminal ✅ +- ✅ Hỗ trợ màu ANSI với phát hiện TTY +- ✅ Hỗ trợ biến môi trường NO_COLOR +- ✅ Hàm màu: `setup_colors()`, `msg_critical()`, `msg_warning()`, `msg_success()`, `msg_info()`, `msg_section()` +- ✅ Nâng cao cảnh báo PATH (hướng dẫn từng bước) +- ✅ Cải thiện thông báo API key GLM (hướng dẫn có thể hành động) +- ✅ Thay thế tất cả emoji bằng ký tự ASCII ([!], [OK], [X], [i]) +- ✅ Thông báo lỗi trong khung sử dụng Unicode box-drawing +- ✅ Định dạng nhất quán trên tất cả các script + +#### Xử lý PATH macOS ✅ +- ✅ Thư mục cài đặt cụ thể theo nền tảng: + - macOS: /usr/local/bin (đã có trong PATH) + - Linux: ~/.local/bin + - Windows: ~/.ccs +- ✅ Xác nhận quyền trước khi cài đặt +- ✅ Tự động migration từ vị trí macOS cũ +- ✅ Dọn dẹp legacy trong uninstaller +- ✅ Hiển thị vị trí cài đặt trong output --version +- ✅ Duy trì tính tương thích đa nền tảng + +#### Kiểm tra & Xác nhận ✅ +- ✅ Xác nhận cú pháp (bash -n) +- ✅ Kiểm tra output màu trên các terminal +- ✅ Xác nhận phát hiện TTY +- ✅ Độ chính xác phát hiện nền tảng +- ✅ Xác nhận kiểm tra quyền +- ✅ Logic migration được kiểm tra +- ✅ **Sửa test uninstall hoàn thành** (57/57 tests passed) + +#### Chuyển đổi npm Package ✅ +- ✅ **BREAKING:** Di chuyển executables từ root sang thư mục lib/ +- ✅ Thêm package.json với bin field để hỗ trợ npm package +- ✅ Tạo bin/ccs.js entry point đa nền tảng Node.js +- ✅ Cập nhật script cài đặt (install.sh, install.ps1) để hỗ trợ cấu trúc lib/ +- ✅ Sửa phát hiện chế độ cài đặt git và sao chép executable +- ✅ Thêm script đồng bộ hóa phiên bản (sync-version.js, check-executables.js) +- ✅ Kiểm tra toàn diện tất cả các phương thức cài đặt (npm, curl, irm, git) +- ✅ Code review passed với điểm 9.7/10 +- ✅ npm package sẵn sàng để publish: `npm install -g @kaitranntt/ccs` + +**Tính năng chính của npm Package:** +- Phân phối package đa nền tảng qua npm registry +- Cấu hình PATH tự động qua npm bin symlinks +- Phát hiện nền tảng và spawning executable phù hợp +- Tương thích đầy đủ với các phương thức cài đặt truyền thống +- Nguồn chân lý duy nhất cho quản lý phiên bản +- Sẵn sàng tự động hóa CI/CD với GitHub Actions + +**Chỉ số chính:** +- Tỷ lệ pass test: 100% +- Kích thước npm package: < 100KB +- Thời gian cài đặt: < 30 giây +- Điểm code review: 9.7/10 (Xuất sắc) +- Tương thích đa nền tảng: 100% +- Tất cả phương thức cài đặt được xác nhận: npm, curl, irm, git + +--- + +### Giai đoạn 4: Nâng cao PowerShell 7+ & Node.js (HOÀN THÀNH - Tháng 11, 2025) ✅ + +**Trạng thái:** 100% Hoàn thành +**Timeline:** 4 Tháng 11, 2025 +**Phiên bản:** 2.3.0 + +#### Hoàn thành Sửa Cú pháp PowerShell 7+ ✅ +- ✅ Sửa lỗi escaping ampersand trong chuỗi đa dòng (dòng 184, 293) +- ✅ Thay thế ký tự pipe bằng ký tự box-drawing (│) để tránh xung đột parser +- ✅ Sửa escaping pattern regex để xác nhận bảo mật (dòng 103) +- ✅ Chuyển đổi tất cả chuỗi đa dòng sang here-strings (`@"...@"`) để tương thích PowerShell 7+ +- ✅ Duy trì tương thích ngược đầy đủ với PowerShell 5.1 +- ✅ Tất cả lỗi parser PowerShell được giải quyết + +#### Hoàn thành Triển khai Node.js Độc Lập ✅ +- ✅ Tạo `bin/helpers.js` với các hàm utility (định dạng màu, mở rộng path, xác nhận) +- ✅ Tạo `bin/claude-detector.js` với phát hiện Claude CLI đa nền tảng +- ✅ Tạo `bin/config-manager.js` với đọc và xác nhận config JSON +- ✅ Tái cấu trúc `bin/ccs.js` thành triển khai độc lập (không shell spawning) +- ✅ Triển khai tất cả các lệnh đặc biệt (--version, --help, --install, --uninstall) +- ✅ Thêm phát hiện profile thông minh và xử lý lỗi +- ✅ Duy trì tính năng tương thích đầy đủ với phiên bản bash/PowerShell +- ✅ Cải thiện hiệu suất 60% so với cách tiếp cận shell-spawning + +#### Hoàn thành Kiểm tra & Xác nhận ✅ +- ✅ Tạo `tests/fixtures/` với các file config mẫu +- ✅ Tạo `tests/unit/helpers.test.js` để xác nhận hàm utility +- ✅ Tạo `tests/integration/special-commands.test.js` để kiểm tra end-to-end +- ✅ Xác nhận tất cả lệnh đặc biệt hoạt động đúng +- ✅ Xác nhận xử lý lỗi cho profiles không hợp lệ +- ✅ Xác nhận phát hiện và thực thi Claude CLI +- ✅ Đạt độ bao phủ test 95% +- ✅ Điểm code review: 9.5/10 (Xuất sắc) + +#### Nâng cao Tương thích Đa Nền tảng ✅ +- ✅ Windows PowerShell 5.1: Hoạt động hoàn hảo +- ✅ Windows PowerShell 7+: Hoạt động hoàn hảo (tất cả vấn đề được giải quyết) +- ✅ Windows Node.js: Hoạt động hoàn hảo +- ✅ macOS/Linux bash: Hoạt động hoàn hảo +- ✅ macOS/Linux Node.js: Hoạt động hoàn hảo +- ✅ Hành vi nhất quán trên tất cả các nền tảng + +#### Kết quả chính ✅ +- **Hiệu suất**: Nhanh hơn 60% với triển khai Node.js độc lập +- **Tương thích**: Hỗ trợ đầy đủ PowerShell 7+ trong khi duy trì tương thích PowerShell 5.1 +- **Đáng tin cậy**: Xử lý lỗi toàn diện với thông báo người dùng rõ ràng +- **Bảo mật**: Duy trì xác nhận mạnh mẽ không có lỗ hổng mới +- **Kiểm tra**: Độ bao phủ 95% với thành công test tích hợp 100% +- **Chất lượng**: Điểm code review xuất sắc (PowerShell: 9/10, Node.js: 9.5/10) + +--- + +### Giai đoạn 5: Triển khai npm Package & Tích hợp Hệ sinh thái (HIỆN TẠI - Tháng 11, 2025) 🚀 + +**Trạng thái:** npm Package Đã Publish & Sẵn sàng, Lập kế hoạch Tích hợp Hệ sinh thái +**Timeline:** 4-30 Tháng 11, 2025 +**Phiên bản mục tiêu:** 2.3.0 + +#### Nhiệm vụ Release npm Package 🎯 +- ✅ Chuyển đổi package hoàn thành (executables → lib/) +- ✅ Tất cả phương thức cài đặt hoạt động (npm, curl, irm, git) +- ✅ Code review passed (điểm 9.7/10) +- ✅ Tương thích PowerShell 7+ được triển khai +- ✅ Triển khai Node.js độc lập hoàn thành +- ✅ Publish npm registry hoàn thành +- ✅ Nâng cao hỗ trợ đa nền tảng được xác nhận +- 📋 Cập nhật tài liệu cho cài đặt npm +- 📋 Hướng dẫn migration cho người dùng hiện tại +- 📋 Kế hoạch bảo trì installer truyền thống + +#### Chiến lược Phương pháp Cài đặt +**Phương pháp Chính được Khuyến nghị:** +- `npm install -g @kaitranntt/ccs` (đa nền tảng, cập nhật tự động) + +**Phương pháp Truyền thống (Được duy trì để tương thích):** +- macOS/Linux: `curl -fsSL ccs.kaitran.ca/install | bash` +- Windows: `irm ccs.kaitran.ca/install | iex` + +**Chế độ Phát triển:** +- Git clone: `./installers/install.sh` + +--- + +### Giai đoạn 6: Tích hợp Hệ sinh thái (LÊN KẾ HOẠCH - Q1 2026) + +**Trạng thái:** Lập kế hoạch +**Timeline:** Tháng 1-3, 2026 +**Phiên bản mục tiêu:** 2.4.0 + +**Tính năng Lên kế hoạch:** + +#### Các tính năng Tích hợp +- [ ] Ví dụ tích hợp CI/CD +- [ ] Hỗ trợ Docker +- [ ] Shell completion (bash/zsh/fish) +- [ ] Thư viện cấu hình presets +- [ ] Hỗ trợ multi-profile (vượt qua glm/default) + +#### Giám sát & Phân tích +- [ ] Telemetry sử dụng (opt-in) +- [ ] Theo dõi thành công cài đặt +- [ ] Hệ thống báo cáo lỗi +- [ ] Chỉ số hiệu suất + +#### Trải nghiệm Nhà phát triển +- [ ] Kiến trúc hệ thống plugin +- [ ] Templates profile tùy chỉnh +- [ ] Chuyển đổi tự động dựa trên môi trường +- [ ] Tích hợp với các wrapper Claude khác + +**Timeline ước tính:** 3-4 tháng +**Yêu cầu tài nguyên:** 1 nhà phát triển, đóng góp cộng đồng + +--- + +### Giai đoạn 7: Tính năng Premium (LÊN KẾ HOẠCH - Q2 2026) + +**Trạng thái:** Ý tưởng +**Timeline:** Tháng 4-6, 2026 +**Phiên bản mục tiêu:** 3.0.0 + +**Tính năng Tiềm năng:** + +#### Khả năng Nâng cao +- [ ] Theo dõi chi phí model +- [ ] Phân tích sử dụng token +- [ ] Lựa chọn model tự động dựa trên loại tác vụ +- [ ] Phát hiện rate limit và tự động chuyển đổi +- [ ] Hỗ trợ multi-provider (OpenAI, Gemini, v.v.) + +#### Tính năng Cộng đồng +- [ ] Thị trường chia sẻ profile +- [ ] Lời chứng thực và nghiên cứu tình huống người dùng +- [ ] Kỹ năng đóng góp cộng đồng +- [ ] Bảng điều khiển thống kê sử dụng + +#### Tính năng Enterprise +- [ ] Quản lý cấu hình đội nhóm +- [ ] Thực thi chính sách tập trung +- [ ] Ghi nhật ký audit +- [ ] Tích hợp SSO + +**Điểm Quyết định:** Nhu cầu người dùng và sẵn có tài nguyên + +--- + +## Lịch Sử Phiên Bản + +### Các Phiên bản Đã Phát Hành + +| Phiên bản | Ngày Phát Hành | Điểm Nổi Bật | Trạng Thái | +|-----------|----------------|-------------|------------| +| 1.0.0 | 2025-10-31 | Phiên bản đầu tiên | Ổn định | +| 1.1.0 | 2025-11-01 | Hỗ trợ git worktree | Ổn định | +| 2.0.0 | 2025-11-02 | Đơn giản hóa lớn | Ổn định | +| 2.1.0 | 2025-11-02 | Tính nhất quán Windows | Ổn định | +| 2.1.1 | 2025-11-02 | Sửa phân tích đối số | Ổn định | +| 2.1.2 | 2025-11-02 | Sửa cài đặt 404 | Ổn định | +| 2.1.3 | 2025-11-02 | Cập nhật tài liệu | Ổn định | +| 2.1.4 | 2025-11-03 | Cải tiến output terminal | Ổn định | +| 2.2.0 | 2025-11-04 | Chuyển đổi npm package | Sẵn sàng Sản xuất | +| 2.3.0 | 2025-11-04 | Nâng cao PowerShell 7+ & Node.js | Sẵn sàng Sản xuất | + +### Đang Phát Triển + +| Phiên bản | Ngày Mục Tiêu | Trạng Thái | Tiến độ | +|-----------|---------------|------------|----------| +| None | - | Tất cả nhiệm vụ hoàn thành | 100% | + +### Lên Kế Hoạch + +| Phiên bản | Ngày Mục Tiêu | Lĩnh vực Tập trung | +|-----------|---------------|-------------------| +| 2.4.0 | 2026-Q1 | Tích hợp hệ sinh thái | +| 3.0.0 | 2026-Q2 | Tính năng premium | + +--- + +## Changelog + +### [2.3.0] - 2025-11-04 (Nâng cao PowerShell 7+ & Node.js) + +#### Thêm +- **Tương thích đầy đủ PowerShell 7+**: Tất cả lỗi parser được giải quyết sử dụng chuyển đổi here-string +- **Triển khai Node.js Độc lập**: Zero phụ thuộc shell với cải thiện hiệu suất 60% +- **Phát hiện Claude CLI Đa nền tảng**: Chuỗi ưu tiên fallback (CCS_CLAUDE_PATH → PATH → các vị trí phổ biến) +- **Suite Test Toàn diện**: Độ bao phủ test 95% với unit và integration tests +- **Thông báo Lỗi Nâng cao**: Phản hồi rõ ràng, có thể hành động với khắc phục sự cố cụ thể theo nền tảng +- **Phát hiện Profile Thông minh**: Cải thiện xác nhận và xử lý fallback + +#### Thay đổi +- **Kiến trúc Script PowerShell**: Chuyển đổi chuỗi đa dòng sang here-strings (`@"...@"`) +- **Xử lý Ký tự**: Thay thế ký tự pipe bằng ký tự box-drawing (│) để tương thích PowerShell 7+ +- **Hiệu suất**: Nhanh hơn 60% với triển khai Node.js độc lập +- **Xử lý Lỗi**: Nâng cao trải nghiệm người dùng với các bước khắc phục sự cố chi tiết +- **Tính nhất quán Đa nền tảng**: Hành vi thống nhất trên Windows PowerShell 5.1/7+, macOS và Linux + +#### Sửa +- **Lỗi Parser PowerShell 7+**: Giải quyết các vấn đề escaping ampersand trong chuỗi đa dòng +- **Xung đột Ký tự Pipe**: Sửa các vấn đề cú pháp với ký tự pipe trong PowerShell 7+ +- **Xác nhận Bảo mật**: Sửa escaping pattern regex để tương thích đa nền tảng +- **Vấn đề Phụ thuộc Shell**: Loại bỏ shell spawning với triển khai Node.js độc lập +- **Phát hiện Đa nền tảng**: Nâng cao phát hiện đường dẫn Claude CLI với logic fallback toàn diện + +#### Chi tiết Kỹ thuật +- **Files Sửa đổi**: `ccs.ps1`, `installers/install.ps1`, `bin/ccs.js`, `bin/helpers.js`, `bin/claude-detector.js`, `bin/config-manager.js` +- **Files Test Mới**: `tests/fixtures/`, `tests/unit/helpers.test.js`, `tests/integration/special-commands.test.js` +- **Chỉ số Hiệu suất**: Cải thiện 60% tốc độ thực thi, giảm 30% sử dụng memory +- **Điểm Code Review**: Sửa PowerShell: 9/10, Triển khai Node.js: 9.5/10 +- **Độ bao phủ Test**: 95% tổng thể, thành công test tích hợp 100% +- **Ma trận Tương thích**: Windows PowerShell 5.1/7+, macOS/Linux bash/Node.js - tất cả hoạt động + +#### Phương pháp Cài đặt (Tất cả Nâng cao) +- **npm (Được khuyến nghị)**: `npm install -g @kaitranntt/ccs` - Bây giờ với triển khai Node.js độc lập +- **Unix Truyền thống**: `curl -fsSL ccs.kaitran.ca/install | bash` - Tương thích PowerShell 7+ +- **Windows Truyền thống**: `irm ccs.kaitran.ca/install | iex` - Tương thích PowerShell 7+ +- **Git Phát triển**: `./installers/install.sh` - Nâng cao với xử lý lỗi tốt hơn + +#### Thay đổi Đột phá +- Không - Hoàn toàn tương thích ngược với các cấu hình hiện tại + +### [2.2.0] - 2025-11-04 (Chuyển đổi npm Package) + +#### ⚠️ THAY ĐỔI ĐỘT PHÁ +- **Cấu trúc Package**: Di chuyển executables từ thư mục root sang thư mục `lib/` +- **Cài đặt**: npm package bây giờ hỗ trợ phân phối đa nền tảng + +#### Thêm +- **Hỗ trợ npm Package**: `npm install -g @kaitranntt/ccs` để cài đặt đa nền tảng dễ dàng +- **Entry Point Đa nền tảng**: `bin/ccs.js` wrapper Node.js với phát hiện nền tảng +- **Quản lý Phiên bản**: `scripts/sync-version.js` và `scripts/check-executables.js` để nhất quán +- **Metadata Package**: package.json hoàn chỉnh với bin field và tên package có phạm vi (@kaitranntt/ccs) + +#### Thay đổi +- **Cấu trúc Thư mục**: `ccs` và `ccs.ps1` di chuyển sang thư mục `lib/` +- **Script Cài đặt**: Cập nhật install.sh và install.ps1 để hỗ trợ thư mục lib/ +- **Phát hiện Chế độ Git**: Sửa để hoạt động với cấu trúc lib/ mới +- **Logic Sao chép Executable**: Cập nhật cho cả chế độ cài đặt git và độc lập + +#### Sửa +- **Đường dẫn Script Cài đặt**: Sửa tham chiếu thư mục lib/ trong install.sh (dòng 24, 416-418) +- **Cài đặt PowerShell**: Sửa tham chiếu thư mục lib/ trong install.ps1 (dòng 23, 235-240) +- **Chế độ Cài đặt Git**: Giải quyết các vấn đề phát hiện với cấu trúc thư mục mới + +#### Chi tiết Kỹ thuật +- **Files Sửa đổi**: package.json, bin/ccs.js, lib/ccs, lib/ccs.ps1, installers/install.sh, installers/install.ps1 +- **Scripts Mới**: scripts/sync-version.js, scripts/check-executables.js +- **Kiểm tra**: Tất cả phương thức cài đặt được xác nhận (npm, curl, irm, git) +- **Code Review**: Passed với điểm 9.7/10 +- **Kích thước Package**: < 100KB +- **Thay đổi Đột phá**: Chỉ ảnh hưởng cấu trúc package, chức năng CLI không thay đổi + +#### Phương pháp Cài đặt (Tất cả Hoạt động) +- **npm (Được khuyến nghị)**: `npm install -g @kaitranntt/ccs` +- **Unix Truyền thống**: `curl -fsSL ccs.kaitran.ca/install | bash` +- **Windows Truyền thống**: `irm ccs.kaitran.ca/install | iex` +- **Git Phát triển**: `./installers/install.sh` + +--- + +## Chỉ số Thành công + +### Trạng thái Hiện tại (v2.3.0 - Sẵn sàng Sản xuất với Hỗ trợ Nâng cao) + +| Chỉ số | Hiện tại | Mục tiêu | Trạng thái | +|--------|----------|----------|------------| +| Tỷ lệ Thành công Cài đặt | 100% | >95% | ✅ Vượt | +| Tỷ lệ Pass Test | 100% | >90% | ✅ Vượt | +| Độ bao phủ Test | 95% | >90% | ✅ Vượt | +| Độ bao phủ Test Uninstall | 100% (57/57) | >95% | ✅ Vượt | +| Lỗ hổng Bảo mật | 0 | 0 | ✅ Hoàn hảo | +| Điểm Chất lượng Code | Xuất sắc (9.5/10) | Tốt+ | ✅ Vượt | +| Tính nhất quán Đa nền tảng | 100% | 100% | ✅ Hoàn hảo | +| Tương thích PowerShell 7+ | 100% | Hoạt động | ✅ Hoàn thành | +| Hiệu suất Node.js | Nhanh hơn 60% | Cải thiện | ✅ Vượt | +| Độ bao phủ Tài liệu | 100% | >90% | ✅ Vượt | +| Chức năng npm Package | 100% | Hoạt động | ✅ Hoàn thành | + +--- + +## Nợ Kỹ thuật + +### Nợ Hiện tại (v2.3.0) + +**KHÔNG** - Tất cả các mục quan trọng và ưu tiên cao đã được giải quyết. + +--- + +## Đánh giá Rủi ro + +### Rủi ro Hiện tại + +**KHÔNG** - Tất cả rủi ro đã được giảm thiểu hoặc giải quyết. + +--- + +## Phụ thuộc + +### Phụ thuộc Ngoài + +| Phụ thuộc | Phiên bản | Bắt buộc | Trạng thái | +|------------|-----------|----------|------------| +| Claude CLI | 2.0.31+ | Có | Ổn định | +| jq | 1.6+ | Tùy chọn | Ổn định | +| bash | 3.2+ | Có (Unix) | Ổn định | +| PowerShell | 5.1+ | Có (Windows) | Ổn định | + +--- + +## Cộng đồng & Tiếp nhận + +### Các Thành tựu Gần đây + +1. **Release v2.3.0** (2025-11-04) ✅ HOÀN THÀNH + - Tương thích đầy đủ PowerShell 7+ + - Triển khai Node.js độc lập + - Cải thiện hiệu suất 60% + - Suite test toàn diện (độ bao phủ 95%) + - Nâng cao hỗ trợ đa nền tảng + +2. **Release v2.2.0** (2025-11-04) ✅ HOÀN THÀNH + - Chuyển đổi npm package + - Hỗ trợ phân phối đa nền tảng + - Tất cả phương thức cài đặt hoạt động + +3. **Release v2.1.4** (2025-11-03) ✅ HOÀN THÀNH + - Cải tiến output terminal + - Xử lý PATH macOS + - Nâng cao trải nghiệm người dùng + +--- + +## Đóng góp + +Xem [CONTRIBUTING.md](./contributing.md) để có hướng dẫn. + +**Các lĩnh vực cần đóng góp:** +- Kiểm tra trên các nền tảng bổ sung +- Cải tiến tài liệu +- Gợi ý tính năng +- Báo cáo lỗi +- Code reviews + +--- + +**Lộ trình Duy trì Bởi:** Trưởng dự án & Điều phối viên Hệ thống +**Tần suất Xem xét:** Sau mỗi release, cập nhật hàng tháng +**Xem xét Tiếp theo:** Post release v2.2.0 npm package (Tháng 11, 2025) \ No newline at end of file diff --git a/docs/vi/testing-requirements.vi.md b/docs/vi/testing-requirements.vi.md new file mode 100644 index 00000000..b20317de --- /dev/null +++ b/docs/vi/testing-requirements.vi.md @@ -0,0 +1,380 @@ +# Yêu cầu & Quy trình Kiểm tra CCS + +**Phiên bản:** 2.1.4 +**Cập nhật lần cuối:** 2025-11-03 +**Trạng thái:** Hoạt động + +## Tổng quan + +Tài liệu này vạch ra các yêu cầu và quy trình kiểm tra toàn diện cho dự án CCS (Claude Code Switch). Tuân thủ các hướng dẫn này đảm bảo các bản phát hành nhất quán, đáng tin cậy và tương thích đa nền tảng. + +## Cấu trúc Suite Test + +### Các File Test Chính + +| File Test | Mục đích | Độ bao phủ | Nền tảng | +|-----------|---------|------------|-----------| +| `tests/uninstall-test.sh` | Xác nhận chức năng gỡ cài đặt | 20 tests | Unix/Linux/macOS | +| `tests/uninstall-test.ps1` | Xác nhận chức năng gỡ cài đặt | 20 tests | Windows | +| `tests/edge-cases.sh` | Kiểm tra trường hợp biên toàn diện | 37 tests | Unix/Linux/macOS | +| `tests/edge-cases.ps1` | Kiểm tra trường hợp biên toàn diện | 37 tests | Windows | + +### Các Danh mục Test + +#### 1. Tests Chức năng Gỡ cài đặt (20 tests) +**File:** `tests/uninstall-test.sh` / `tests/uninstall-test.ps1` + +**Các phần:** +1. **Gỡ cài đặt Trống (3 tests)** + - Lệnh thực thi không có lỗi + - Thông báo "nothing to uninstall" phù hợp + - Báo cáo 0 items bị xóa đúng + +2. **Vòng lặp Cài đặt/Gỡ cài đặt (5 tests)** + - Thực thi gỡ cài đặt sạch + - Xóa file lệnh ccs.md + - Xóa thư mục kỹ năng ccs-delegation + - Bảo tồn các lệnh khác (non-invasive) + - Bảo tồn các kỹ năng khác (non-invasive) + +3. **Idempotency (2 tests)** + - Gỡ cài đặt lần thứ hai thành công + - Báo cáo không tìm thấy gì trong các lần chạy tiếp theo + +4. **Định dạng Output (4 tests)** + - Chứa headers vẽ khung + - Hiển thị thông báo thành công + - Cung cấp hướng dẫn cài đặt lại + +5. **Tests Tích hợp (3 tests)** + - Không có lỗi profile khi gỡ cài đặt + - Lệnh version vẫn hoạt động + - Lệnh help vẫn hoạt động + +6. **Trường hợp Biên (3 tests)** + - Xử lý các cài đặt một phần + - Xử lý các thư mục thiếu + - Quản lý các kịch bản lỗi một cách khéo léo + +#### 2. Trường hợp Biên Toàn diện (37 tests) +**File:** `tests/edge-cases.sh` / `tests/edge-cases.ps1` + +**Các lĩnh vực bao phủ:** +- **Lệnh Version (3 tests)** +- **Lệnh Help (2 tests)** +- **Phân tích Đối số (6 tests)** +- **Lệnh Profile (4 tests)** +- **Xử lý Lỗi (3 tests)** +- **Trường hợp Biên (6 tests)** +- **Xác nhận Cấu hình (6 tests)** +- **Mô phỏng Sử dụng Thực tế (3 tests)** +- **Tests Cụ thể theo Nền tảng (4 tests)** + +## Yêu cầu Môi trường Kiểm tra + +### Cô lập Biến Môi trường + +**Yêu cầu Quan trọng:** Tất cả tests phải sử dụng thư mục HOME cô lập để ngăn tác động đến dữ liệu người dùng. + +**Mẫu Triển khai:** +```bash +# Unix/Linux/macOS +HOME=/tmp/test-ccs-home ./ccs --install +HOME=/tmp/test-ccs-home ./ccs --uninstall + +# Windows PowerShell +$env:HOME = "C:\temp\test-ccs-home" +.\ccs.ps1 --install +.\ccs.ps1 --uninstall +``` + +**Yêu cầu Xác nhận:** +- ✅ Cài đặt sử dụng thư mục test (không `~/.claude`) +- ✅ Gỡ cài đặt chỉ xóa file từ thư mục test +- ✅ Thư mục người dùng thực tế hoàn toàn không bị ảnh hưởng +- ✅ Đạt được cô lập test hoàn hảo + +### Tương thích Đa nền tảng + +**Mẫu Cụ thể theo Nền tảng:** +- **Phiên bản Bash:** Sử dụng `$HOME/.claude` trực tiếp +- **Phiên bản PowerShell:** Sử dụng mẫu ưu tiên HOME với fallback USERPROFILE + +**Mẫu PowerShell:** +```powershell +$HomeDir = if ($env:HOME) { $env:HOME } else { $env:USERPROFILE } +``` + +## Quy trình Thực thi Test + +### Điều kiện tiên quyết + +1. **Môi trường Test Sạch** + ```bash + # Xóa bất kỳ cài đặt CCS hiện có + rm -rf ~/.ccs ~/.local/bin/ccs + ``` + +2. **Công cụ Bắt buộc** + - bash 3.2+ (Unix/Linux/macOS) + - PowerShell 5.1+ (Windows) + - Claude CLI 2.0.31+ + - jq 1.6+ (tùy chọn, để xác nhận JSON) + +### Chạy Tests + +#### Unix/Linux/macOS +```bash +# Điều hướng đến thư mục CCS +cd /path/to/ccs + +# Chạy tests gỡ cài đặt +./tests/uninstall-test.sh + +# Chạy tests trường hợp biên +./tests/edge-cases.sh + +# Chạy tất cả tests (suite đầy đủ) +./tests/uninstall-test.sh && ./tests/edge-cases.sh +``` + +#### Windows +```powershell +# Điều hướng đến thư mục CCS +cd C:\path\to\ccs + +# Chạy tests gỡ cài đặt +.\tests\uninstall-test.ps1 + +# Chạy tests trường hợp biên +.\tests\edge-cases.ps1 + +# Chạy tất cả tests (suite đầy đủ) +.\tests\uninstall-test.ps1; .\tests\edge-cases.ps1 +``` + +### Kết quả Mong đợi + +**Tiêu chí Thành công:** +- **Tỷ lệ Pass Test Tổng thể:** 100% +- **Suite Test Cá nhân:** Mỗi phải pass 100% +- **Cô lập Môi trường:** Không tác động đến dữ liệu người dùng +- **Tính nhất quán Đa nền tảng:** Hành vi giống hệt nhau trên các nền tảng + +**Output Mẫu:** +``` +=== CCS Uninstall Test Results === +Total Tests: 20 +Passed: 20 (100%) +Failed: 0 (0%) +Status: ✅ ALL TESTS PASSED +``` + +## Tiêu chuẩn Chất lượng + +### Yêu cầu Chất lượng Code + +1. **Xác nhận Cú pháp** + ```bash + # Kiểm tra cú pháp bash + bash -n ccs + bash -n install.sh + bash -n uninstall.sh + + # Kiểm tra cú pháp PowerShell + Get-Command Test-Path -Syntax ccs.ps1 + ``` + +2. **Tính nhất quán Mẫu** + - Mẫu biến môi trường ưu tiên HOME + - Xử lý lỗi nhất quán + - Định dạng output đồng nhất + +3. **Xác nhận Bảo mật** + - Không tác động đến dữ liệu người dùng + - Quyền file thích hợp + - Không truy cập thư mục trái phép + +### Yêu cầu Kiểm tra Chức năng + +1. **Kiểm tra Happy Path** + - Các hoạt động tiêu chuẩn hoạt động hoàn hảo + - Các hành vi mặc định hoạt động như mong đợi + - Các workflows người dùng hoàn thành thành công + +2. **Xử lý Trường hợp Biên** + - Xử lý mạnh mẽ các đầu vào không mong đợi + - Chế độ thất bại khéo léo + - Thông báo lỗi rõ ràng với giải pháp có thể hành động + +3. **Kiểm tra Tích hợp** + - Tích hợp CLI với tất cả các lệnh + - Các hoạt động PATH hoạt động đúng + - Xử lý biến môi trường đáng tin cậy + +## Chỉ số Độ bao phủ Test + +### Độ bao phủ Hiện tại (v2.1.4) + +| Danh mục Test | Tests | Tỷ lệ Pass | Trạng thái | +|---------------|-------|------------|------------| +| Chức năng Gỡ cài đặt | 20 | 100% | ✅ Hoàn thành | +| Trường hợp Biên | 37 | 100% | ✅ Hoàn thành | +| Xác nhận Đa nền tảng | 57 | 100% | ✅ Hoàn thành | +| Cô lập Môi trường | 57 | 100% | ✅ Hoàn thành | +| **Tổng độ bao phủ** | **57** | **100%** | **✅ Hoàn thành** | + +### Mục tiêu Độ bao phủ cho các Bản phát hành Tương lai + +| Chỉ số | Mục tiêu | Trạng thái Hiện tại | +|--------|----------|---------------------| +| Tỷ lệ Pass Test | >95% | 100% ✅ | +| Độ bao phủ Đa nền tảng | 100% | 100% ✅ | +| Độ bao phủ Trường hợp Biên | >90% | 100% ✅ | +| Cô lập Môi trường | 100% | 100% ✅ | +| Xác nhận Bảo mật | 100% | 100% ✅ | + +## Tích hợp Kiểm tra Tự động + +### Yêu cầu Pipeline CI/CD + +**Tích hợp Được khuyến nghị:** +```yaml +# Ví dụ GitHub Actions +- name: Run CCS Tests + run: | + ./tests/uninstall-test.sh + ./tests/edge-cases.sh +``` + +**Lợi ích Tự động hóa Test:** +- Thực thi test nhất quán +- Phát hiện sớm các hồi quy +- Xác nhận đa nền tảng +- Cổng chất lượng tự động + +### Kiểm tra Hiệu suất + +**Tiêu chuẩn Thực thi Test:** +- **Tests Gỡ cài đặt:** ~15 giây +- **Tests Trường hợp Biên:** ~45 giây +- **Suite Tổng thể:** ~60 giây +- **Sử dụng Memory:** Tối thiểu +- **Disk I/O:** Được kiểm soát và tạm thời + +## Quy trình Bảo trì Test + +### Khi Cập nhật Tests + +1. **Thêm Tính năng Mới** + - Thêm các test case tương ứng + - Cập nhật tài liệu test + - Xác nhận tương thích đa nền tảng + +2. **Triển khai Sửa lỗi** + - Thêm các test hồi quy cho lỗi đã sửa + - Xác nhận sửa không làm hỏng chức năng hiện có + - Cập nhật chỉ số độ bao phủ test + +3. **Thay đổi Nền tảng** + - Kiểm tra trên các phiên bản nền tảng mới + - Cập nhật các test case cụ thể theo nền tảng + - Xác nhận tính tương thích + +### Quy trình Xem xét Test + +1. **Tích hợp Xem xét Code** + - Tests được xem xét cùng với các thay đổi code + - Đảm bảo độ bao phủ test cho chức năng mới + - Xác nhận chất lượng và hiệu quả test + +2. **Xác nhận Release** + - Thực thi suite test đầy đủ trước các bản phát hành + - Xác nhận đa nền tảng + - Đánh giá hiệu suất + +## Khắc phục Thất bại Test + +### Các vấn đề Phổ biến + +1. **Xung đột Biến Môi trường** + - **Triệu chứng:** Tests ảnh hưởng đến thư mục người dùng + - **Giải pháp:** Xác nhận mẫu cô lập HOME + - **Phòng ngừa:** Luôn sử dụng môi trường test cô lập + +2. **Vấn đề Quyền** + - **Triệu chứng:** Thất bại hoạt động file + - **Giải pháp:** Kiểm tra quyền và đường dẫn file + - **Phòng ngừa:** Xác nhận điều kiện tiên quyết trước khi test + +3. **Thất bại Cụ thể theo Nền tảng** + - **Triệu chứng:** Tests pass trên một nền tảng, fail trên nền tảng khác + - **Giải pháp:** Xem lại các đường dẫn code cụ thể theo nền tảng + - **Phòng ngừa:** Kiểm tra trên tất cả các nền tảng được hỗ trợ + +### Quy trình Gỡ lỗi + +1. **Bật Output Chi tiết** + ```bash + # Thêm flags debug vào các script test + ./tests/uninstall-test.sh --verbose + ``` + +2. **Cô lập Tests Thất bại** + ```bash + # Chạy các phần test cá nhân + ./tests/uninstall-test.sh --section=empty-uninstall + ``` + +3. **Xác nhận Môi trường** + ```bash + # Kiểm tra biến môi trường + echo "HOME: $HOME" + echo "USERPROFILE: $USERPROFILE" + ``` + +## Thực hành Tốt nhất + +### Hướng dẫn Phát triển Test + +1. **Cô lập Test** + - Không bao giờ sửa dữ liệu người dùng trong tests + - Sử dụng thư mục tạm thời cho tất cả các hoạt động file + - Dọn dẹp tất cả các tạo phẩm test + +2. **Cân nhắc Đa nền tảng** + - Kiểm tra trên tất cả các nền tảng được hỗ trợ + - Sử dụng mẫu không phụ thuộc nền tảng khi có thể + - Xử lý các khác biệt cụ thể theo nền tảng một cách rõ ràng + +3. **Khả năng Bảo trì** + - Tài liệu test rõ ràng + - Cấu trúc test nhất quán + - Tiện ích test có thể tái sử dụng + +### Cải tiến Liên tục + +1. **Phân tích Độ bao phủ Test** + - Đánh giá độ bao phủ định kỳ + - Xác định các đường dẫn code chưa được test + - Ưu tiên các lĩnh vực rủi ro cao + +2. **Giám sát Hiệu suất** + - Theo dõi thời gian thực thi test + - Xác nhận các hồi quy hiệu suất + - Tối ưu hóa các test case chậm + +3. **Chỉ số Chất lượng** + - Theo dõi tỷ lệ pass test + - Theo dõi tỷ lệ phát hiện lỗi + - Đo lường hiệu quả test + +--- + +**Duy trì Bởi:** Kỹ sư QA & Đội phát triển +**Tần suất Xem xét:** Hàng tháng hoặc sau các bản phát hành lớn +**Cập nhật lần cuối:** 2025-11-03 + +**Câu hỏi chưa giải quyết:** Không +**Chặn khối:** Không +**Xem xét Tiếp theo:** Post release v2.1.4 \ No newline at end of file diff --git a/docs/vi/version-management.vi.md b/docs/vi/version-management.vi.md new file mode 100644 index 00000000..59cc6c4b --- /dev/null +++ b/docs/vi/version-management.vi.md @@ -0,0 +1,99 @@ +# Quản Lý Phiên Bản + +## Tổng Quan + +CCS sử dụng hệ thống quản lý phiên bản tập trung để đảm bảo tính nhất quán trên tất cả các thành phần. + +## Vị Trí Phiên Bản + +Số phiên bản phải được đồng bộ hóa trên các tệp sau: + +1. **`VERSION`** - Tệp phiên bản chính (được đọc bởi ccs/ccs.ps1 tại runtime) +2. **`installers/install.sh`** - Hardcoded cho các cài đặt độc lập (`curl | bash`) +3. **`installers/install.ps1`** - Hardcoded cho các cài đặt độc lập (`irm | iex`) + +## Tại Sao Hardcoded Phiên Bản trong Installers? + +Khi người dùng chạy: +- `curl -fsSL ccs.kaitran.ca/install | bash` +- `irm ccs.kaitran.ca/install.ps1 | iex` + +Script installer được tải xuống và thực thi trực tiếp **không** có tệp VERSION. Do đó, installers phải có phiên bản hardcoded làm dự phòng. + +Đối với các cài đặt dựa trên git, tệp VERSION sẽ được đọc nếu có, ghi đè phiên bản hardcoded. + +## Cập Nhật Phiên Bản + +### Phương Pháp Tự Động (Được khuyến nghị) + +Sử dụng script được cung cấp để tự động tăng phiên bản: + +```bash +# Tăng phiên bản patch (2.1.1 -> 2.1.2) +./scripts/bump-version.sh patch + +# Tăng phiên bản minor (2.1.1 -> 2.2.0) +./scripts/bump-version.sh minor + +# Tăng phiên bản major (2.1.1 -> 3.0.0) +./scripts/bump-version.sh major +``` + +Điều này cập nhật: +- Tệp VERSION +- installers/install.sh (phiên bản hardcoded) +- installers/install.ps1 (phiên bản hardcoded) + +### Phương Pháp Thủ Công + +Nếu cập nhật thủ công, cập nhật phiên bản ở CẢ BA vị trí: + +1. **Tệp VERSION**: + ```bash + echo "2.1.2" > VERSION + ``` + +2. **installers/install.sh** (dòng ~34): + ```bash + CCS_VERSION="2.1.2" + ``` + +3. **installers/install.ps1** (dòng ~33): + ```powershell + $CcsVersion = "2.1.2" + ``` + +## Checklist Release + +Khi phát hành phiên bản mới: + +- [ ] Cập nhật phiên bản sử dụng `./scripts/bump-version.sh X.Y.Z` +- [ ] Xem lại các thay đổi: `git diff` +- [ ] Cập nhật CHANGELOG.md với ghi chú release +- [ ] Commit các thay đổi: `git commit -am "chore: bump version to X.Y.Z"` +- [ ] Push: `git push` +- [ ] Xác nhận CloudFlare worker phục vụ installer đã cập nhật + +## Hiển Thị Phiên Bản + +Sau khi cài đặt, người dùng có thể kiểm tra phiên bản: + +```bash +# Hiển thị phiên bản CCS (từ tệp VERSION nếu có) +ccs --version + +# Hiển thị phiên bản Claude CLI +ccs version +``` + +## Semantic Versioning + +CCS tuân theo [Semantic Versioning](https://semver.org/): + +- **MAJOR** (X.0.0): Thay đổi đột phá +- **MINOR** (0.X.0): Tính năng mới (tương thích ngược) +- **PATCH** (0.0.X): Sửa lỗi + +Phiên bản hiện tại: **2.1.1** +- 2.1.0: Thêm tính năng delegation tác vụ +- 2.1.1: Sửa lỗi phân tích đối số (cờ được coi là profiles) \ No newline at end of file diff --git a/package.json b/package.json index 5d89b10a..784247a2 100644 --- a/package.json +++ b/package.json @@ -29,6 +29,7 @@ "files": [ "bin/", "lib/", + "scripts/", "config/", "VERSION", "README.md", @@ -47,6 +48,7 @@ "test": "bash tests/edge-cases.sh", "prepublishOnly": "node scripts/sync-version.js", "prepack": "node scripts/sync-version.js", - "prepare": "node scripts/check-executables.js" + "prepare": "node scripts/check-executables.js", + "postinstall": "node scripts/postinstall.js" } } diff --git a/scripts/postinstall.js b/scripts/postinstall.js new file mode 100755 index 00000000..a8ce9d74 --- /dev/null +++ b/scripts/postinstall.js @@ -0,0 +1,99 @@ +#!/usr/bin/env node +'use strict'; + +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +/** + * CCS Postinstall Script + * Automatically creates config files in ~/.ccs/ after npm install + * + * Runs when: npm install -g @kaitranntt/ccs + * Idempotent: Safe to run multiple times (won't overwrite existing configs) + * Cross-platform: Works on Unix, macOS, Windows + */ + +function createConfigFiles() { + try { + // Get user home directory (cross-platform) + const homedir = os.homedir(); + const ccsDir = path.join(homedir, '.ccs'); + + // Create ~/.ccs/ directory if missing + if (!fs.existsSync(ccsDir)) { + fs.mkdirSync(ccsDir, { recursive: true, mode: 0o755 }); + console.log('[OK] Created directory: ~/.ccs/'); + } + + // Create config.json if missing + const configPath = path.join(ccsDir, 'config.json'); + if (!fs.existsSync(configPath)) { + const config = { + profiles: { + glm: '~/.ccs/glm.settings.json', + default: '~/.claude/settings.json' + } + }; + + // Atomic write: temp file → rename + const tmpPath = `${configPath}.tmp`; + fs.writeFileSync(tmpPath, JSON.stringify(config, null, 2) + '\n', 'utf8'); + fs.renameSync(tmpPath, configPath); + + console.log('[OK] Created config: ~/.ccs/config.json'); + } else { + console.log('[OK] Config exists: ~/.ccs/config.json (preserved)'); + } + + // Create glm.settings.json if missing + const glmSettingsPath = path.join(ccsDir, 'glm.settings.json'); + if (!fs.existsSync(glmSettingsPath)) { + const glmSettings = { + env: { + ANTHROPIC_BASE_URL: 'https://api.z.ai/api/anthropic', + ANTHROPIC_AUTH_TOKEN: 'YOUR_GLM_API_KEY_HERE', + 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' + } + }; + + // Atomic write + const tmpPath = `${glmSettingsPath}.tmp`; + fs.writeFileSync(tmpPath, JSON.stringify(glmSettings, null, 2) + '\n', 'utf8'); + fs.renameSync(tmpPath, glmSettingsPath); + + console.log('[OK] Created GLM profile: ~/.ccs/glm.settings.json'); + console.log(''); + console.log(' [!] Configure GLM API key:'); + console.log(' 1. Get key from: https://api.z.ai'); + console.log(' 2. Edit: ~/.ccs/glm.settings.json'); + console.log(' 3. Replace: YOUR_GLM_API_KEY_HERE'); + } else { + console.log('[OK] GLM profile exists: ~/.ccs/glm.settings.json (preserved)'); + } + + console.log(''); + console.log('[OK] CCS configuration ready!'); + console.log(' Run: ccs --version'); + + } catch (err) { + // Silent failure: don't break npm install + console.warn(''); + console.warn('[!] Could not auto-create CCS configuration'); + console.warn(` Error: ${err.message}`); + console.warn(''); + console.warn(' Manual setup:'); + console.warn(' mkdir -p ~/.ccs'); + console.warn(' # See: https://github.com/kaitranntt/ccs#configuration'); + console.warn(''); + + // Don't exit with error code - allow npm install to succeed + process.exit(0); + } +} + +// Run postinstall +createConfigFiles(); diff --git a/tests/edge-cases.sh b/tests/edge-cases.sh index fcf8f59f..c5d72133 100755 --- a/tests/edge-cases.sh +++ b/tests/edge-cases.sh @@ -297,6 +297,51 @@ test_case "Version without ./ prefix" "Can run 'ccs --version' from PATH" bash - [[ \$output =~ 2\\.1\\.1|CCS ]] || [[ \$output =~ 'command not found' ]] " +# ============================================================================ +# SECTION 10: NPM POSTINSTALL TESTING +# ============================================================================ +echo "" +echo -e "${YELLOW}===== SECTION 10: NPM POSTINSTALL TESTING =====${NC}" + +test_case "NPM postinstall creates config.json" "Postinstall creates ~/.ccs/config.json" bash -c " + # Clean slate + rm -rf ~/.ccs + + # Run postinstall script directly + cd /tmp/ccs-test + node scripts/postinstall.js > /dev/null 2>&1 + + # Verify config created + [[ -f ~/.ccs/config.json ]] +" + +test_case "NPM postinstall creates glm.settings.json" "Postinstall creates GLM template" bash -c " + # Should exist from previous test + [[ -f ~/.ccs/glm.settings.json ]] +" + +test_case "NPM postinstall is idempotent" "Running postinstall twice is safe" bash -c " + # Create custom config + echo '{\"profiles\":{\"custom\":\"~/.custom.json\"}}' > ~/.ccs/config.json + + # Run postinstall again + cd /tmp/ccs-test + node scripts/postinstall.js > /dev/null 2>&1 + + # Verify custom config preserved + grep -q 'custom' ~/.ccs/config.json +" + +test_case "NPM postinstall output format" "Postinstall uses ASCII symbols" bash -c " + # Clean and re-run with output + rm -rf ~/.ccs + cd /tmp/ccs-test + output=\$(node scripts/postinstall.js 2>&1) + + # Check for ASCII symbols ([OK], [!]) not emojis + [[ \$output =~ \\[OK\\]|\\[!\\] ]] +" + # ============================================================================ # FINAL RESULTS # ============================================================================