From be958e992d543b0673fc9c1e3c38b756c72b7612 Mon Sep 17 00:00:00 2001 From: kaitranntt Date: Thu, 6 Nov 2025 07:01:20 -0500 Subject: [PATCH] chore(docs): remove Vietnamese documentation and outdated development files --- docs/development-workflow.md | 311 ----------- docs/project-roadmap.md | 807 ----------------------------- docs/vi/development-workflow.vi.md | 300 ----------- docs/vi/project-roadmap.vi.md | 506 ------------------ docs/vi/testing-requirements.vi.md | 380 -------------- docs/vi/version-management.vi.md | 99 ---- 6 files changed, 2403 deletions(-) delete mode 100644 docs/development-workflow.md delete mode 100644 docs/project-roadmap.md delete mode 100644 docs/vi/development-workflow.vi.md delete mode 100644 docs/vi/project-roadmap.vi.md delete mode 100644 docs/vi/testing-requirements.vi.md delete mode 100644 docs/vi/version-management.vi.md diff --git a/docs/development-workflow.md b/docs/development-workflow.md deleted file mode 100644 index 8bca1387..00000000 --- a/docs/development-workflow.md +++ /dev/null @@ -1,311 +0,0 @@ -# CCS Workflow Documentation - -Workflow documentation for CCS v2.4.4 covering installation, runtime behavior, and troubleshooting. Recently simplified with 35% code reduction while maintaining all functionality. - ---- - -## Architecture Overview - -### Simplified Architecture (Post-Optimization) - -``` -User Command: ccs [profile] [claude-args...] - │ - ▼ -┌─────────────────┐ -│ ccs (Node.js) │ ← Simplified entry point (139 lines, reduced from 232) -└────────┬────────┘ - │ - ├─ 1. Parse arguments & detect profile - ├─ 2. Read ~/.ccs/config.json (simplified) - ├─ 3. Get settings path (streamlined) - ├─ 4. Detect Claude CLI (optimized) - │ - ▼ -┌─────────────────┐ -│ Unified Spawn │ ← Single execClaude() function (consolidated logic) -└────────┬────────┘ - │ - ▼ - ┌──────────────────┐ - │ Claude CLI │ - └──────────────────┘ -``` - -### Key Components (Simplified) - -1. **ccs.js**: Main entry point with consolidated spawn logic -2. **config-manager.js**: Streamlined configuration handling (73 lines, reduced from 134) -3. **claude-detector.js**: Optimized Claude CLI detection (72 lines, reduced from 101) -4. **helpers.js**: Essential utilities only (48 lines, reduced from 64) - -### Recent Simplification Achievements - -- **35% code reduction**: 1,315 → 855 lines while maintaining all functionality -- **Consolidated spawn logic**: Single `execClaude()` function replaces 3 duplicate blocks -- **Removed security theater**: Eliminated unnecessary validation functions -- **Simplified error handling**: Direct console.error instead of complex formatting -- **Deduplicated platform checks**: Centralized cross-platform logic - -### Design Principles - -- **YAGNI**: Only essential features, no "just in case" code -- **KISS**: Simple delegation with unified logic -- **DRY**: Single source of truth for each concern -- **Performance**: Optimized for speed and maintainability - ---- - -## Installation Workflow - -### Process - -1. **Platform Detection**: Windows vs Unix -2. **Create directories**: `~/.ccs/`, `~/.local/bin` -3. **Clean old installs**: Remove old `/usr/local/bin` installations (if CCS symlinks) -4. **Install executables**: - - Git mode: Symlink from repo - - Standalone: Download from GitHub -5. **Install .claude folder**: Commands and skills -6. **Create config**: `config.json` if missing -7. **Create GLM profile**: `glm.settings.json` if missing -8. **Backup**: Single `config.json.backup` (overwrites) -9. **Validate**: Check JSON syntax -10. **Configure PATH**: Auto-detect shell, add to profile -11. **Display instructions**: Shell reload, GLM API key (if needed) - -### Unified Install Location (v2.2.0+) - -**All Unix Systems**: `~/.local/bin/ccs` -- User-writable, no sudo required -- Auto PATH configuration for bash, zsh, fish -- Idempotent setup (safe to run multiple times) - -**Windows**: `%USERPROFILE%\.ccs\ccs.ps1` -- Auto-added to user PATH - -### Shell Profile Management - -**Auto-detection** (`detect_shell_profile()`): -- Extracts shell from `$SHELL` variable -- Returns appropriate profile file: - - bash: `~/.bashrc` (Linux) or `~/.bash_profile` (macOS) - - zsh: `~/.zshrc` - - fish: `~/.config/fish/config.fish` -- Validates shell name (alphanumeric only) -- Defaults to `~/.bashrc` if unknown - -**PATH checking** (`check_path_configured()`): -- Tests if `~/.local/bin` in current `$PATH` -- Returns true if already configured - -**PATH addition** (`add_to_path()`): -- Creates profile file if missing -- Checks for existing CCS marker comment -- Adds shell-specific PATH export: - - bash/zsh: `export PATH="$HOME/.local/bin:$PATH"` - - fish: `set -gx PATH $HOME/.local/bin $PATH` -- Idempotent: skips if already added - -**Configuration workflow** (`configure_shell_path()`): -- Checks if PATH already configured -- Detects shell profile -- Adds PATH entry -- Shows reload instructions -- Fallback to manual instructions if fails - -### Files Created - -**Executable Locations**: -- macOS / Linux: `~/.local/bin/ccs` (symlink to `~/.ccs/ccs`) -- Windows: `%USERPROFILE%\.ccs\ccs.ps1` - -**Configuration Directory** (`~/.ccs/`): -``` -~/.ccs/ -├── ccs # Main executable (symlink target) -├── config.json # Profile mappings -├── config.json.backup # Single backup (no timestamp) -├── glm.settings.json # GLM profile -├── VERSION # Version file -├── 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 [args] -``` - -### Windows - -``` -ccs [profile] [args] - ↓ -Read config.json - ↓ -Lookup profile → settings file path - ↓ -Validate file exists - ↓ -exec claude --settings [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 | - ---- - -## Terminal Output Standards - -### Color Functions - -**TTY Detection**: Colors only shown when output is to terminal (not piped/redirected) -```bash -if [[ -t 2 ]] && [[ -z "${NO_COLOR:-}" ]]; then - # Enable colors -else - # Disable colors -fi -``` - -**NO_COLOR Support**: Respects `NO_COLOR` environment variable -```bash -export NO_COLOR=1 # Disables all color output -``` - -### Message Types - -**Error Messages** (red, boxed): -``` -╔═════════════════════════════════════════════╗ -║ ERROR ║ -╚═════════════════════════════════════════════╝ -``` - -**Critical Messages** (red, boxed, "ACTION REQUIRED"): -``` -╔═════════════════════════════════════════════╗ -║ ACTION REQUIRED ║ -╚═════════════════════════════════════════════╝ -``` - -**Warning Messages** (yellow): -``` -[!] WARNING -``` - -**Success Messages** (green): -``` -[OK] Success message -``` - -**Info Messages** (plain): -``` -[i] Information -``` - -### ASCII Symbols (No Emojis) - -All output uses ASCII symbols for compatibility: -- `[OK]` - Success -- `[!]` - Warning -- `[X]` - Error/Failure -- `[i]` - Information - -## Key Points - -1. **Installation**: Unified location (`~/.local/bin`), auto PATH config, validates JSON -2. **Runtime**: Simple delegation to Claude CLI via `--settings` flag -3. **Cross-platform**: Unified Unix location, identical behavior -4. **Non-invasive**: Never touches `~/.claude/settings.json` -5. **Validation**: JSON syntax checking prevents errors -6. **Backup**: Single file, overwrites each install -7. **Terminal Output**: TTY detection, NO_COLOR support, ASCII symbols only -8. **Shell Support**: Auto-detects bash, zsh, fish -9. **Simplified Architecture**: 35% code reduction with unified spawn logic -10. **Enhanced Performance**: Optimized for speed and maintainability - ---- - -**Version**: v2.4.4 -**Updated**: 2025-11-05 -**Architecture**: Simplified with consolidated components and improved maintainability diff --git a/docs/project-roadmap.md b/docs/project-roadmap.md deleted file mode 100644 index 72a8a074..00000000 --- a/docs/project-roadmap.md +++ /dev/null @@ -1,807 +0,0 @@ -# CCS Project Roadmap - -**Project:** CCS (Claude Code Switch) -**Version:** 2.3.0 (PowerShell 7+ & Node.js Enhancement) -**Last Updated:** 2025-11-04 -**Status:** Production Ready with Enhanced Cross-Platform Support - ---- - -## Project Overview - -CCS is a lightweight CLI wrapper for instant switching between Claude Sonnet 4.5 and GLM 4.6 AI models. Built with YAGNI/KISS/DRY principles, CCS provides seamless model switching without modifying Claude settings files. - -**Core Value:** One command, zero downtime, right model for each task. - ---- - -## Development Phases - -### Phase 1: Foundation (COMPLETE - Q4 2025) ✅ - -**Status:** 100% Complete -**Timeline:** Oct 31 - Nov 1, 2025 -**Version:** 1.0.0 - 1.1.0 - -**Achievements:** -- ✅ Profile-based switching between Claude and GLM -- ✅ Cross-platform support (macOS, Linux, Windows) -- ✅ One-line installation via curl/irm -- ✅ Auto-detection of current provider -- ✅ Git worktree and submodule support -- ✅ Enhanced GLM profile with default model variables - -**Key Metrics:** -- Installation success rate: 100% -- Platforms supported: 3 (macOS, Linux, Windows) -- Dependencies: jq (optional), Claude CLI - ---- - -### Phase 2: Simplification & Stability (COMPLETE - Nov 2025) ✅ - -**Status:** 100% Complete -**Timeline:** Nov 2, 2025 -**Version:** 2.0.0 - 2.1.3 - -**Major Changes:** - -#### v2.0.0 - Architecture Simplification -- ✅ **BREAKING:** Removed `ccs son` profile (use `ccs` for Claude subscription) -- ✅ Config structure simplified (single glm fallback only) -- ✅ Non-invasive approach (never modifies ~/.claude/settings.json) -- ✅ Smart installer with validation and self-healing -- ✅ Migration detection and auto-upgrade from v1.x -- ✅ Config backup with timestamp -- ✅ VERSION file for centralized version management -- ✅ GitHub Actions workflow for CloudFlare Worker deployment - -**Critical Fixes:** -- ✅ PowerShell env var crash (strict filtering prevents non-string values) -- ✅ JSON validation for all config files -- ✅ Better error messages with actionable solutions - -#### v2.1.0 - Windows Consistency -- ✅ Windows PowerShell uses `--settings` flag (same as Unix) -- ✅ Removed 64 lines of env var management (27% code reduction) -- ✅ Cross-platform approach identical (macOS/Linux/Windows) - -#### v2.1.1 - Windows Support Enhancement -- ✅ `--version` and `--help` flags work correctly -- ✅ Argument parsing improved (handles flags before profile) - -#### v2.1.2 - Installation Fix -- ✅ Fixed 404 error in standalone installations -- ✅ Corrected GitHub raw URL path (uninstall.sh location) -- ✅ 68/68 tests passing (100% pass rate) -- ✅ Zero security vulnerabilities - -#### v2.1.3 - Documentation & Reliability -- ✅ Comprehensive documentation updates -- ✅ Enhanced error handling -- ✅ README refactoring for clarity - -**Key Metrics:** -- Code reduction: 27% in PowerShell version -- Test coverage: 100% pass rate (68 tests) -- Security vulnerabilities: 0 -- Installation success: 100% - ---- - -### Phase 3: User Experience Enhancement (COMPLETED - Nov 2025) ✅ - -**Status:** 100% Complete -**Timeline:** Nov 2-4, 2025 -**Version:** 2.1.4 (Released) + 2.2.0 (npm Package) - -**Completed Features:** - -#### Terminal Output Improvements ✅ -- ✅ ANSI color support with TTY detection -- ✅ NO_COLOR environment variable support -- ✅ Color functions: `setup_colors()`, `msg_critical()`, `msg_warning()`, `msg_success()`, `msg_info()`, `msg_section()` -- ✅ Enhanced PATH warnings (step-by-step instructions) -- ✅ Improved GLM API key notices (actionable guidance) -- ✅ All emojis replaced with ASCII symbols ([!], [OK], [X], [i]) -- ✅ Boxed error messages using Unicode box-drawing -- ✅ Consistent formatting across all scripts - -#### macOS PATH Handling ✅ -- ✅ Platform-specific install directories: - - macOS: /usr/local/bin (already in PATH) - - Linux: ~/.local/bin - - Windows: ~/.ccs -- ✅ Permission validation before installation -- ✅ Automatic migration from old macOS location -- ✅ Legacy cleanup in uninstaller -- ✅ Install location shown in --version output -- ✅ Cross-platform parity maintained - -#### Testing & Validation ✅ -- ✅ Syntax validation (bash -n) -- ✅ Color output tests across terminals -- ✅ TTY detection verification -- ✅ Platform detection accuracy -- ✅ Permission check validation -- ✅ Migration logic tested -- ✅ **Uninstall test fixes completed** (57/57 tests passing) - -#### npm Package Transformation ✅ -- ✅ **BREAKING:** Moved executables from root to lib/ directory -- ✅ Added package.json with bin field for npm package support -- ✅ Created bin/ccs.js cross-platform Node.js entry point -- ✅ Updated installation scripts (install.sh, install.ps1) to support lib/ structure -- ✅ Fixed git installation mode detection and executable copying -- ✅ Added version synchronization scripts (sync-version.js, check-executables.js) -- ✅ Comprehensive testing of all installation methods (npm, curl, irm, git) -- ✅ Code review passed with 9.7/10 rating -- ✅ npm package ready for publication: `npm install -g @kaitranntt/ccs` - -**Key npm Package Features:** -- Cross-platform package distribution via npm registry -- Automatic PATH configuration via npm bin symlinks -- Platform detection and appropriate executable spawning -- Full compatibility with traditional installation methods -- Single source of truth for version management -- CI/CD automation ready with GitHub Actions - -**Key Metrics:** -- Test pass rate: 100% -- npm package size: < 100KB -- Installation time: < 30 seconds -- Code review score: 9.7/10 (Excellent) -- Cross-platform compatibility: 100% -- All installation methods validated: npm, curl, irm, git - -**Key Metrics:** -- Test pass rate: 100% -- Platforms tested: macOS 13+, Ubuntu 22.04/24.04, Windows 11 -- Security review: Approved -- Code quality: Excellent -- Uninstall test coverage: 100% (57 tests) - ---- - -### Phase 4: PowerShell 7+ & Node.js Enhancement (COMPLETED - Nov 2025) ✅ - -**Status:** 100% Complete -**Timeline:** Nov 4, 2025 -**Version:** 2.3.0 - -#### Completed PowerShell 7+ Syntax Fixes ✅ -- ✅ Fixed ampersand escaping in multi-line strings (lines 184, 293) -- ✅ Replaced pipe characters with box-drawing characters (│) to avoid parser conflicts -- ✅ Fixed regex pattern escaping for security validation (line 103) -- ✅ Converted all multi-line strings to here-strings (`@"...@"`) for PowerShell 7+ compatibility -- ✅ Maintained full backward compatibility with PowerShell 5.1 -- ✅ All PowerShell parser errors resolved - -#### Completed Node.js Standalone Implementation ✅ -- ✅ Created `bin/helpers.js` with utility functions (color formatting, path expansion, validation) -- ✅ Created `bin/claude-detector.js` with cross-platform Claude CLI detection -- ✅ Created `bin/config-manager.js` with JSON config reading and validation -- ✅ Refactored `bin/ccs.js` to standalone implementation (no shell spawning) -- ✅ Implemented all special commands (--version, --help, --install, --uninstall) -- ✅ Added smart profile detection and error handling -- ✅ Maintained full functional parity with bash/PowerShell versions -- ✅ 60% performance improvement over shell-spawning approach - -#### Completed Testing & Validation ✅ -- ✅ Created `tests/fixtures/` with sample config files -- ✅ Created `tests/unit/helpers.test.js` for utility function validation -- ✅ Created `tests/integration/special-commands.test.js` for end-to-end testing -- ✅ Validated all special commands work correctly -- ✅ Confirmed error handling for invalid profiles -- ✅ Verified Claude CLI detection and execution -- ✅ 95% test coverage achieved -- ✅ Code review score: 9.5/10 (Outstanding) - -#### Cross-Platform Compatibility Enhanced ✅ -- ✅ Windows PowerShell 5.1: Working perfectly -- ✅ Windows PowerShell 7+: Working perfectly (all issues resolved) -- ✅ Windows Node.js: Working perfectly -- ✅ macOS/Linux bash: Working perfectly -- ✅ macOS/Linux Node.js: Working perfectly -- ✅ Consistent behavior across all platforms - -#### Key Results ✅ -- **Performance**: 60% faster execution with Node.js standalone implementation -- **Compatibility**: Full PowerShell 7+ support while maintaining PowerShell 5.1 compatibility -- **Reliability**: Comprehensive error handling with clear user messages -- **Security**: Maintained robust validation with no new vulnerabilities -- **Testing**: 95% test coverage with 100% integration test success -- **Quality**: Outstanding code review scores (PowerShell: 9/10, Node.js: 9.5/10) - ---- - -### Phase 5: npm Package Deployment & Ecosystem Integration (COMPLETED - Nov 2025) ✅ - -**Status:** npm Package Published & Optimized, All Objectives Exceeded -**Timeline:** Nov 4-5, 2025 -**Target Version:** 2.3.0 - -#### npm Package Release Tasks ✅ COMPLETED -- ✅ Package transformation completed (executables → lib/) -- ✅ All installation methods working (npm, curl, irm, git) -- ✅ Code review passed (9.7/10 rating) -- ✅ PowerShell 7+ compatibility implemented -- ✅ Node.js standalone implementation completed -- ✅ npm registry publishing completed -- ✅ Enhanced cross-platform support validated -- ✅ **NEW: CCS npm Package Simplification Project** - Code Optimization Initiative -- ✅ **NEW: 38% code reduction achieved, exceeding 35% target** -- ✅ **NEW: All functionality preserved with improved maintainability** - -#### CCS npm Package Simplification Results ✅ -**Project**: CCS npm Package Code Simplification (2025-11-05) -**Status**: COMPLETED ✅ - -**Achievement Summary**: -- **Total lines reduced**: 502 lines (38% reduction) - EXCEEDED target of 35% -- **Source code**: 706 → 332 lines (-374 lines, 53% reduction) -- **Tests**: 609 → 481 lines (-128 lines, 21% reduction) -- **Overall**: 1,315 → 813 lines (-502 lines, 38% reduction) - -**Completed Optimization Phases**: -1. ✅ Phase 1: Consolidate spawn logic (120 lines saved) -2. ✅ Phase 2: Remove security theater (45 lines saved) -3. ✅ Phase 3: Collapse error messages (80 lines saved) -4. ✅ Phase 4: Deduplicate platform checks (15 lines saved) -5. ✅ Testing: All 39 tests passing -6. ✅ Code Review: Approved for production - -**Quality Assurance**: -- All tests passing (39/39) -- No syntax errors -- Code review approved (EXCELLENT rating) -- Functionality preserved 100% -- Security maintained/improved -- Performance enhanced (38% less code to load) - -#### Installation Method Strategy -**Primary Recommended Method:** -- `npm install -g @kaitranntt/ccs` (cross-platform, automatic updates) - -**Traditional Methods (Maintained for compatibility):** -- macOS/Linux: `curl -fsSL ccs.kaitran.ca/install | bash` -- Windows: `irm ccs.kaitran.ca/install | iex` - -**Development Mode:** -- Git clone: `./installers/install.sh` - ---- - -### Phase 6: Ecosystem Integration (PLANNED - Q1 2026) - -**Status:** Planning -**Timeline:** Jan-Mar 2026 -**Target Version:** 2.4.0 - -**Planned Features:** - -#### Integration Features -- [ ] CI/CD integration examples -- [ ] Docker support -- [ ] Shell completion (bash/zsh/fish) -- [ ] Configuration presets library -- [ ] Multi-profile support (beyond glm/default) - -#### Monitoring & Analytics -- [ ] Usage telemetry (opt-in) -- [ ] Installation success tracking -- [ ] Error reporting system -- [ ] Performance metrics - -#### Developer Experience -- [ ] Plugin system architecture -- [ ] Custom profile templates -- [ ] Environment-based auto-switching -- [ ] Integration with other Claude wrappers - -**Estimated Timeline:** 3-4 months -**Resource Requirements:** 1 developer, community contributions - ---- - -### Phase 7: Premium Features (PLANNED - Q2 2026) - -**Status:** Concept -**Timeline:** Apr-Jun 2026 -**Target Version:** 3.0.0 - -**Potential Features:** - -#### Advanced Capabilities -- [ ] Model cost tracking -- [ ] Token usage analytics -- [ ] Automatic model selection based on task type -- [ ] Rate limit detection and auto-switching -- [ ] Multi-provider support (OpenAI, Gemini, etc.) - -#### Community Features -- [ ] Profile sharing marketplace -- [ ] User testimonials and case studies -- [ ] Community-contributed skills -- [ ] Usage statistics dashboard - -#### Enterprise Features -- [ ] Team configuration management -- [ ] Centralized policy enforcement -- [ ] Audit logging -- [ ] SSO integration - -**Decision Point:** User demand and resource availability - ---- - -## Version History - -### Released Versions - -| Version | Release Date | Highlights | Status | -|---------|--------------|------------|--------| -| 1.0.0 | 2025-10-31 | Initial release | Stable | -| 1.1.0 | 2025-11-01 | Git worktree support | Stable | -| 2.0.0 | 2025-11-02 | Major simplification | Stable | -| 2.1.0 | 2025-11-02 | Windows consistency | Stable | -| 2.1.1 | 2025-11-02 | Argument parsing fix | Stable | -| 2.1.2 | 2025-11-02 | Installation 404 fix | Stable | -| 2.1.3 | 2025-11-02 | Documentation update | Stable | -| 2.1.4 | 2025-11-03 | Terminal output improvements | Stable | -| 2.2.0 | 2025-11-04 | npm package transformation | Production Ready | -| 2.3.0 | 2025-11-04 | PowerShell 7+ & Node.js enhancement | Production Ready | -| 2.3.1 | 2025-11-05 | Code simplification & optimization | Production Ready | - -### In Development - -| Version | Target Date | Status | Progress | -|---------|-------------|--------|----------| -| None | - | All tasks completed | 100% | - -### Planned - -| Version | Target Date | Focus Area | -|---------|-------------|------------| -| 2.4.0 | 2026-Q1 | Ecosystem integration | -| 3.0.0 | 2026-Q2 | Premium features | - ---- - -## Changelog - -### [2.3.1] - 2025-11-05 (Code Simplification & Optimization) - -#### Added -- **CCS npm Package Simplification**: Major code optimization initiative completed -- **Performance Enhancement**: 38% overall code reduction, improving maintainability and load times -- **KISS Principle Implementation**: Simplified architecture following YAGNI guidelines -- **Enhanced Error Handling**: Streamlined error messages without functionality loss - -#### Changed -- **Code Structure**: Reduced from 1,315 to 813 lines (-502 lines, 38% reduction) -- **Source Code**: Optimized from 706 to 332 lines (-374 lines, 53% reduction) -- **Test Suite**: Streamlined from 609 to 481 lines (-128 lines, 21% reduction) -- **Spawn Logic**: Consolidated 3 separate blocks into single `execClaude()` function -- **Error Messages**: Simplified from complex Unicode formatting to clean console.error output -- **Platform Detection**: Unified cross-platform logic while maintaining compatibility - -#### Fixed -- **Code Duplication**: Eliminated redundant validation functions and security theater -- **Security Functions**: Removed unnecessary functions while maintaining security posture -- **Platform Checks**: Deduplicated Windows .cmd/.bat detection logic -- **Function Complexity**: Reduced cyclomatic complexity across all modules - -#### Technical Details -- **Target vs Actual**: Target 35% reduction, achieved 38% ✅ EXCEEDED TARGET -- **Functionality Preservation**: 100% - all core features maintained -- **Security Status**: Maintained/improved - no new vulnerabilities introduced -- **Test Coverage**: 100% preserved (39/39 tests passing) -- **Code Review**: EXCELLENT rating - approved for production deployment -- **Performance**: Improved startup time and reduced memory footprint - -#### Breaking Changes -- None - All functionality preserved, simplified internal implementation only - -#### Installation Methods -All installation methods remain unchanged and fully functional: -- **npm (Recommended)**: `npm install -g @kaitranntt/ccs` -- **Traditional Unix**: `curl -fsSL ccs.kaitran.ca/install | bash` -- **Traditional Windows**: `irm ccs.kaitran.ca/install | iex` -- **Git Development**: `./installers/install.sh` - -### [2.3.0] - 2025-11-04 (PowerShell 7+ & Node.js Enhancement) - -#### Added -- **PowerShell 7+ Full Compatibility**: All parser errors resolved using here-string conversion -- **Node.js Standalone Implementation**: Zero shell dependencies with 60% performance improvement -- **Cross-Platform Claude CLI Detection**: Priority-based fallback chain (CCS_CLAUDE_PATH → PATH → common locations) -- **Comprehensive Test Suite**: 95% test coverage with unit and integration tests -- **Enhanced Error Messages**: Clear, actionable feedback with platform-specific troubleshooting -- **Smart Profile Detection**: Improved validation and fallback handling - -#### Changed -- **PowerShell Script Architecture**: Multi-line strings converted to here-strings (`@"...@"`) -- **Character Handling**: Pipe characters replaced with box-drawing characters (│) for PowerShell 7+ compatibility -- **Performance**: 60% faster execution with Node.js standalone implementation -- **Error Handling**: Enhanced user experience with detailed troubleshooting steps -- **Cross-Platform Consistency**: Unified behavior across Windows PowerShell 5.1/7+, macOS, and Linux - -#### Fixed -- **PowerShell 7+ Parser Errors**: Resolved ampersand escaping issues in multi-line strings -- **Pipe Character Conflicts**: Fixed syntax issues with pipe characters in PowerShell 7+ -- **Security Validation**: Corrected regex pattern escaping for cross-platform compatibility -- **Shell Dependency Issues**: Eliminated shell spawning with standalone Node.js implementation -- **Cross-Platform Detection**: Enhanced Claude CLI path detection with comprehensive fallback logic - -#### Technical Details -- **Files Modified**: `ccs.ps1`, `installers/install.ps1`, `bin/ccs.js`, `bin/helpers.js`, `bin/claude-detector.js`, `bin/config-manager.js` -- **New Test Files**: `tests/fixtures/`, `tests/unit/helpers.test.js`, `tests/integration/special-commands.test.js` -- **Performance Metrics**: 60% improvement in execution speed, 30% lower memory usage -- **Code Review Scores**: PowerShell fixes: 9/10, Node.js implementation: 9.5/10 -- **Test Coverage**: 95% overall, 100% integration test success -- **Compatibility Matrix**: Windows PowerShell 5.1/7+, macOS/Linux bash/Node.js - all working - -#### Installation Methods (All Enhanced) -- **npm (Recommended)**: `npm install -g @kaitranntt/ccs` - Now with standalone Node.js implementation -- **Traditional Unix**: `curl -fsSL ccs.kaitran.ca/install | bash` - PowerShell 7+ compatible -- **Traditional Windows**: `irm ccs.kaitran.ca/install | iex` - PowerShell 7+ compatible -- **Git Development**: `./installers/install.sh` - Enhanced with better error handling - -#### Breaking Changes -- None - Fully backward compatible with existing configurations - -### [2.2.0] - 2025-11-04 (npm Package Transformation) - -#### ⚠️ BREAKING CHANGES -- **Package Structure**: Moved executables from root directory to `lib/` directory -- **Installation**: npm package now supports cross-platform distribution - -#### Added -- **npm Package Support**: `npm install -g @kaitranntt/ccs` for easy cross-platform installation -- **Cross-Platform Entry Point**: `bin/ccs.js` Node.js wrapper with platform detection -- **Version Management**: `scripts/sync-version.js` and `scripts/check-executables.js` for consistency -- **Package Metadata**: Complete package.json with bin field and scoped package name (@kaitranntt/ccs) - -#### Changed -- **Directory Structure**: `ccs` and `ccs.ps1` moved to `lib/` directory -- **Installation Scripts**: Updated install.sh and install.ps1 for lib/ directory support -- **Git Mode Detection**: Fixed to work with new lib/ structure -- **Executable Copy Logic**: Updated for both git and standalone installation modes - -#### Fixed -- **Installation Script Paths**: Fixed lib/ directory references in install.sh (lines 24, 416-418) -- **PowerShell Installation**: Fixed lib/ directory references in install.ps1 (lines 23, 235-240) -- **Git Installation Mode**: Resolved detection issues with new directory structure - -#### Technical Details -- **Files Modified**: package.json, bin/ccs.js, lib/ccs, lib/ccs.ps1, installers/install.sh, installers/install.ps1 -- **New Scripts**: scripts/sync-version.js, scripts/check-executables.js -- **Testing**: All installation methods validated (npm, curl, irm, git) -- **Code Review**: Passed with 9.7/10 rating -- **Package Size**: < 100KB -- **Breaking Changes**: Only affects package structure, CLI functionality unchanged - -#### Installation Methods (All Working) -- **npm (Recommended)**: `npm install -g @kaitranntt/ccs` -- **Traditional Unix**: `curl -fsSL ccs.kaitran.ca/install | bash` -- **Traditional Windows**: `irm ccs.kaitran.ca/install | iex` -- **Git Development**: `./installers/install.sh` - -### [2.1.4] - 2025-11-03 - -#### Added -- Terminal color support with ANSI codes -- TTY detection for color output -- NO_COLOR environment variable support -- Enhanced error messages with box-drawing characters -- Platform-specific install directories (macOS: /usr/local/bin, Linux: ~/.local/bin) -- Permission validation before installation -- Automatic migration from old macOS install location -- Legacy cleanup in uninstaller -- Install location in --version output - -#### Changed -- All emojis replaced with ASCII symbols -- PATH warnings enhanced with step-by-step instructions -- GLM API key notices improved with actionable guidance -- Error messages use boxed formatting -- Success messages use [OK] prefix -- Warning messages use [!] prefix -- Info messages use [i] prefix - -#### Technical Details -- Files modified: install.sh, install.ps1, ccs, ccs.ps1, uninstall.sh, uninstall.ps1 -- Lines of code changed: ~150 -- Test coverage: 100% pass rate -- Security review: Approved -- Breaking changes: None -- Migration path: Automatic for macOS users - -### [2.1.4] - 2025-11-03 (In Progress) - Uninstall Test Fixes - -#### Fixed -- **CRITICAL:** Environment variable mismatch in uninstall tests (HOME vs USERPROFILE) -- PowerShell Start-Process compatibility issues in test framework -- Test isolation failures affecting user directories - -#### Technical Details -- **Files modified:** ccs.ps1 (lines 47, 152), tests/uninstall-test.ps1 -- **Root cause:** Environment variable pattern inconsistency -- **Solution:** HOME-first pattern with USERPROFILE fallback -- **Test results:** 57/57 tests passing (100% success rate) -- **Code review score:** 9.5/10 (EXCELLENT) -- **Implementation time:** 45 minutes (Quick Fix approach) -- **Cross-platform compatibility:** Fully validated -- **Production status:** APPROVED FOR IMMEDIATE DEPLOYMENT - -### [2.1.3] - 2025-11-02 - -#### Changed -- Documentation updates across all files -- Enhanced error handling -- README refactoring for clarity - -### [2.1.2] - 2025-11-02 - -#### Fixed -- **CRITICAL:** 404 error in standalone installations -- GitHub raw URL path corrected (uninstall.sh location) - -#### Technical Details -- Files changed: install.sh (line 284), VERSION, install.ps1 -- Testing: 68/68 tests passing -- Security: Zero vulnerabilities - -### [2.1.1] - 2025-11-02 - -#### Added -- `--version` and `--help` flags support in Windows - -#### Fixed -- Argument parsing logic (handles flags before profile) - -### [2.1.0] - 2025-11-02 - -#### Changed -- **MAJOR:** Windows PowerShell now uses `--settings` flag -- Removed 64 lines of environment variable management -- Windows and Unix/Linux/macOS use identical approach -- ccs.ps1: 235 lines → 171 lines (27% reduction) - -### [2.0.0] - 2025-11-02 - -#### BREAKING CHANGES -- Removed `ccs son` profile (use `ccs` for Claude subscription) -- Config structure simplified - -#### Added -- `config/` folder with organized templates -- `installers/` folder for clean project structure -- Smart installer with validation -- Non-invasive approach -- Version pinning support -- CHANGELOG.md -- WORKFLOW.md -- Migration detection and auto-migration -- Config backup with timestamp -- JSON validation -- GitHub Actions workflow - -#### Fixed -- **CRITICAL:** PowerShell env var crash -- PowerShell requires `env` object in settings files -- Type validation for environment variables - -### [1.1.0] - 2025-11-01 - -#### Added -- Git worktree and submodule support -- Enhanced GLM profile with default model variables - -#### Fixed -- BASH_SOURCE unbound variable error -- Git worktree detection - -### [1.0.0] - 2025-10-31 - -#### Added -- Initial release -- Profile-based switching -- Cross-platform support -- One-line installation -- Auto-detection of current provider - ---- - -## Success Metrics - -### Current Status (v2.3.1 - Production Ready with Optimized Codebase) - -| Metric | Current | Target | Status | -|--------|---------|--------|--------| -| Installation Success Rate | 100% | >95% | ✅ Exceeding | -| Test Pass Rate | 100% | >90% | ✅ Exceeding | -| Test Coverage | 95% | >90% | ✅ Exceeding | -| Uninstall Test Coverage | 100% (57/57) | >95% | ✅ Exceeding | -| Security Vulnerabilities | 0 | 0 | ✅ Perfect | -| Code Quality Score | Outstanding (9.5/10) | Good+ | ✅ Exceeding | -| Cross-Platform Parity | 100% | 100% | ✅ Perfect | -| PowerShell 7+ Compatibility | 100% | Working | ✅ Complete | -| Node.js Performance | 60% faster | Improvement | ✅ Exceeding | -| Documentation Coverage | 100% | >90% | ✅ Exceeding | -| npm Package Functionality | 100% | Working | ✅ Complete | -| **Code Reduction Achievement** | **38%** | **35% target** | **✅ EXCEEDED TARGET** | -| **Code Maintainability** | **Excellent** | **Improved** | **✅ SIGNIFICANTLY ENHANCED** | - -### Goals for v2.3.0 - ALL ACHIEVED - -| Metric | Target | Achievement | -|--------|--------|-------------| -| PowerShell 7+ Compatibility | 100% working | ✅ All parser errors resolved | -| Node.js Standalone | Full functionality | ✅ 60% performance improvement | -| Test Coverage | >90% | ✅ 95% coverage achieved | -| Code Review Score | >9.0/10 | ✅ 9.5/10 achieved | -| Cross-Platform Parity | 100% | ✅ All platforms working | -| Performance Improvement | >30% | ✅ 60% faster execution | - -### Goals for v2.2.0 - ALL ACHIEVED - -| Metric | Target | Achievement | -|--------|--------|-------------| -| npm Package Size | < 100KB | ✅ < 100KB achieved | -| Installation Time | < 30 seconds | ✅ < 30 seconds achieved | -| Code Review Score | > 9.0/10 | ✅ 9.7/10 achieved | -| Cross-Platform Installers | 100% working | ✅ All methods working | -| Version Synchronization | 100% consistent | ✅ Automated scripts | - ---- - -## Technical Debt - -### Current Debt (v2.3.0) - -**NONE** - All critical and high-priority items resolved. - -### Resolved Debt - -| Item | Severity | Resolved | Version | -|------|----------|----------|---------| -| PowerShell 7+ parser errors | Critical | 2025-11-04 | 2.3.0 | -| Shell dependency limitations | High | 2025-11-04 | 2.3.0 | -| Cross-platform performance | Medium | 2025-11-04 | 2.3.0 | -| Test coverage gaps | Medium | 2025-11-04 | 2.3.0 | -| Uninstall test failures | Critical | 2025-11-03 | 2.1.4 | -| Environment variable mismatch | Critical | 2025-11-03 | 2.1.4 | -| PowerShell env var crash | Critical | 2025-11-02 | 2.0.0 | -| Installation 404 error | Critical | 2025-11-02 | 2.1.2 | -| Windows argument parsing | High | 2025-11-02 | 2.1.1 | -| Code duplication (env vars) | Medium | 2025-11-02 | 2.1.0 | - ---- - -## Risk Assessment - -### Current Risks - -**NONE** - All identified risks mitigated or resolved. - -### Resolved Risks - -| Risk | Impact | Resolution | Date | -|------|--------|------------|------| -| PowerShell 7+ parser errors | Critical | Here-string conversion implementation | 2025-11-04 | -| Shell dependency limitations | High | Node.js standalone implementation | 2025-11-04 | -| Cross-platform performance gaps | Medium | Performance optimization | 2025-11-04 | -| Test coverage deficiencies | Medium | Comprehensive test suite creation | 2025-11-04 | -| Uninstall test failures | Critical | Environment variable pattern fix | 2025-11-03 | -| Test isolation failures | High | HOME-first pattern implementation | 2025-11-03 | -| CCS installation failure (404) | High | Fixed URL path | 2025-11-02 | -| Windows incompatibility | High | Added --settings support | 2025-11-02 | -| macOS PATH issues | Medium | Platform-specific install dirs | 2025-11-03 | -| Terminal color compatibility | Low | Fallback support | 2025-11-03 | - ---- - -## Dependencies - -### External Dependencies - -| Dependency | Version | Required | Status | -|------------|---------|----------|--------| -| Claude CLI | 2.0.31+ | Yes | Stable | -| jq | 1.6+ | Optional | Stable | -| bash | 3.2+ | Yes (Unix) | Stable | -| PowerShell | 5.1+ | Yes (Windows) | Stable | - -### Internal Dependencies - -| Component | Status | Health | -|-----------|--------|--------| -| GitHub raw URLs | Operational | ✅ Stable | -| CloudFlare Worker | Operational | ✅ Stable | -| Version management | Operational | ✅ Stable | -| npm Package | Ready | ✅ Production Ready | -| Installation Scripts | Operational | ✅ All Methods Working | - ---- - -## Community & Adoption - -### Metrics (as of 2025-11-04) - -- GitHub Stars: Growing -- Installation Methods: npm (recommended), curl/irm one-liners -- Platform Distribution: macOS (40%), Linux (35%), Windows (25%) -- User Feedback: Positive -- Community Contributions: Open for PRs -- npm Package: Ready for publication - -### Recent Achievements - -1. **v2.3.0 Release** (2025-11-04) ✅ COMPLETED - - PowerShell 7+ full compatibility - - Node.js standalone implementation - - 60% performance improvement - - Comprehensive test suite (95% coverage) - - Enhanced cross-platform support - -2. **v2.2.0 Release** (2025-11-04) ✅ COMPLETED - - npm package transformation - - Cross-platform distribution support - - All installation methods working - -3. **v2.1.4 Release** (2025-11-03) ✅ COMPLETED - - Terminal output improvements - - macOS PATH handling - - Enhanced user experience - -4. **Documentation Enhancement** (Nov 2025) - - Video tutorials - - Interactive examples - - FAQ expansion - -5. **Community Growth** (Q4 2025) - - User testimonials - - Case studies - - Blog posts - ---- - -## Contributing - -See [CONTRIBUTING.md](./contributing.md) for guidelines. - -**Areas Needing Contribution:** -- Testing on additional platforms -- Documentation improvements -- Feature suggestions -- Bug reports -- Code reviews - ---- - -## Resources - -### Documentation -- [Installation Guide](./installation.md) -- [Configuration](./configuration.md) -- [Usage Examples](./usage.md) -- [Troubleshooting](./troubleshooting.md) -- [Contributing](./contributing.md) - -### Project Links -- GitHub: https://github.com/kaitranntt/ccs -- Installation: https://ccs.kaitran.ca/install -- Issues: https://github.com/kaitranntt/ccs/issues - -### Implementation Plans -- Location: `/home/kai/CloudPersonal/plans/` -- Current: `251102-ccs-terminal-output-path-improvements.md` -- Reports: `/home/kai/CloudPersonal/plans/reports/` - ---- - -**Roadmap Maintained By:** Project Manager & System Orchestrator -**Review Frequency:** After each release, monthly updates -**Next Review:** Post v2.2.0 npm package publication (Nov 2025) diff --git a/docs/vi/development-workflow.vi.md b/docs/vi/development-workflow.vi.md deleted file mode 100644 index 4f7fae3f..00000000 --- a/docs/vi/development-workflow.vi.md +++ /dev/null @@ -1,300 +0,0 @@ -# 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/project-roadmap.vi.md b/docs/vi/project-roadmap.vi.md deleted file mode 100644 index 0193e1d4..00000000 --- a/docs/vi/project-roadmap.vi.md +++ /dev/null @@ -1,506 +0,0 @@ -# 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 deleted file mode 100644 index b20317de..00000000 --- a/docs/vi/testing-requirements.vi.md +++ /dev/null @@ -1,380 +0,0 @@ -# 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 deleted file mode 100644 index 59cc6c4b..00000000 --- a/docs/vi/version-management.vi.md +++ /dev/null @@ -1,99 +0,0 @@ -# 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