diff --git a/README.md b/README.md index a87bdd69..351d1eb5 100644 --- a/README.md +++ b/README.md @@ -46,10 +46,14 @@ bun add -g @kaitranntt/ccs ```
-Alternative: Direct Install (Traditional) +[!] DEPRECATED: Native Shell Installers (Legacy)
+> [!WARNING] +> **These installers are deprecated and will be removed in a future version.** +> They now auto-redirect to npm installation. Please use npm directly. + **macOS / Linux** ```bash curl -fsSL ccs.kaitran.ca/install | bash @@ -60,7 +64,7 @@ curl -fsSL ccs.kaitran.ca/install | bash irm ccs.kaitran.ca/install | iex ``` -**Note:** Traditional installs bypass Node.js routing for faster startup, but npm is prioritized for easier deployment automation. +**Note:** Scripts show deprecation warning and automatically run npm installation if Node.js is available.
@@ -748,15 +752,18 @@ ccs sync ## Uninstall +### npm (Recommended) + +```bash +npm uninstall -g @kaitranntt/ccs +``` +
-

Package Managers

 +Alternative Package Managers
```bash -# npm -npm uninstall -g @kaitranntt/ccs - # yarn yarn global remove @kaitranntt/ccs @@ -770,7 +777,7 @@ bun remove -g @kaitranntt/ccs
-

Official Uninstaller

 +Legacy Uninstallers (for native installs)
diff --git a/docs/codebase-summary.md b/docs/codebase-summary.md index f2bce552..b2839ae2 100644 --- a/docs/codebase-summary.md +++ b/docs/codebase-summary.md @@ -2,27 +2,28 @@ ## Overview -CCS (Claude Code Switch) v4.5.0 is a lightweight CLI wrapper enabling instant profile switching between Claude Sonnet 4.5, GLM 4.6, GLMT (GLM with Thinking), and Kimi for Coding models. Version 4.x introduces AI-powered delegation, selective .claude/ directory symlinking, stream-JSON output, and enhanced shell completion. **Phase 02 (2025-11-27)** completes modular command architecture refactoring with 44.6% main file reduction. v4.5.0 completes transition to Node.js-first architecture with bootstrap-based installers. +CCS (Claude Code Switch) v4.5.0 is a lightweight CLI wrapper enabling instant profile switching between Claude Sonnet 4.5, GLM 4.6, GLMT (GLM with Thinking), and Kimi for Coding models. Version 4.x introduces AI-powered delegation, selective .claude/ directory symlinking, stream-JSON output, and enhanced shell completion. **Phase 02 (2025-11-28)** completes modular command architecture refactoring with 44.6% main file reduction and deprecates native shell installers. v4.5.0 completes transition to npm-first, Node.js-based architecture with bootstrap installers and CSS text-only output (no emojis). ## Version Evolution -### v4.5.0 Architecture (Current, Phase 02 Complete) +### v4.5.0 Architecture (Current, Phase 02 Complete - 2025-11-28) - **Total LOC**: ~8,477 lines (JavaScript/TypeScript) - **Main File**: src/ccs.ts - 593 lines (**44.6% reduction** from 1,071 lines) - **Key Features**: AI delegation, stream-JSON output, shell completion, doctor diagnostics, sync command -- **Phase 02 Modular Commands**: 6 specialized command handlers (version, help, install, doctor, sync, shell-completion) +- **Phase 02 Modular Commands**: 6 specialized command handlers (version, help, install, doctor, sync, shell-completion) + deprecation notices +- **Installation Method**: npm-first (curl/irm scripts deprecated, auto-redirect to npm) - **New Components**: src/commands/, src/utils/shell-executor.ts, src/utils/package-manager-detector.ts - **Architecture**: Modular design with clear separation: auth/, delegation/, glmt/, management/, utils/, commands/, types/ -- **Installation**: Bootstrap-based native installers (requires Node.js 14+, no shell dependencies) +- **Output Format**: Text-only ASCII indicators ([OK], [!], [X], [i]) - no emoji usage per CLAUDE.md ### Evolution Summary - **v2.x**: Vault-based credential encryption (~1,700 LOC) - **v3.0**: Vault removal, login-per-profile (~1,100 LOC, 40% reduction) - **v4.0-4.4.x**: Delegation system, .claude/ sharing, stream-JSON (~8,477 LOC including tests/utils) -- **Phase 02 (2025-11-27)**: Modular command architecture, main file 44.6% reduction -- **v4.5.0**: Bootstrap-based installers, TypeScript npm package with quality gates + modular commands +- **Phase 02 (2025-11-28)**: Modular command architecture, native installer deprecation, main file 44.6% reduction +- **v4.5.0**: npm-first distribution, TypeScript package with quality gates, modular commands, text-only output (no emojis) -## Core Components (Phase 02 Complete - 2025-11-27) +## Core Components (Phase 02 Complete - 2025-11-28) ### 1. Main Entry Point (`src/ccs.ts` - 593 lines, 44.6% reduction) @@ -235,7 +236,7 @@ ccs work "task" 3. Postinstall: ClaudeSymlinkManager creates selective symlinks → `~/.claude/` 4. User can now use `/ccs` (auto-select) and `/ccs:continue` commands -## File Structure (Phase 02 Complete - 2025-11-27) +## File Structure (Phase 02 Complete - 2025-11-28) ``` src/ # TypeScript source files (Phase 02 Modular Architecture) @@ -423,9 +424,16 @@ ccs.js: execClaude(["command"], {CLAUDE_CONFIG_DIR: instancePath}) Claude CLI: Read credentials from instance, execute ``` -## Key Features (v4.3.2) +## Key Features (v4.5.0 - Phase 02 Complete) -### 1. AI-Powered Delegation (v4.0) +### 1. npm-First Installation (Phase 02 - 2025-11-28) +- **Recommended method**: All users directed to npm installation +- **Native installer deprecation**: curl/irm scripts auto-redirect to npm +- **Cross-platform parity**: Single installation method across macOS/Linux/Windows +- **Easy updates**: `npm install -g @kaitranntt/ccs` (version pinning supported) +- **Bootstrap installers**: Replaced shell scripts with Node.js-based installation + +### 2. AI-Powered Delegation (v4.0+) - **Headless execution**: `ccs glm -p "task"` runs without interactive UI - **Stream-JSON output**: Real-time tool visibility (`[Tool] Write: file.js`) - **Session continuation**: `ccs glm:continue -p "follow-up"` resumes last session @@ -433,25 +441,31 @@ Claude CLI: Read credentials from instance, execute - **Signal handling**: Proper Ctrl+C cleanup - **13 tools supported**: Comprehensive Claude Code tool coverage -### 2. Selective .claude/ Symlinking (v4.1) +### 3. Selective .claude/ Symlinking (v4.1) - **Package-provided**: `.claude/` ships with npm, copied to `~/.ccs/.claude/` - **Selective symlinks**: Only CCS items linked to `~/.claude/` - **Non-invasive**: Doesn't overwrite user's commands/skills - **Windows support**: Falls back to copying if symlinks unavailable - **Auto-sync**: `ccs sync` re-creates symlinks -### 3. Enhanced Shell Completion (v4.1.4) +### 4. Enhanced Shell Completion (v4.1.4) - **4 shells**: bash, zsh, fish, PowerShell - **Color-coded**: Commands vs descriptions - **Categorized**: Model profiles, account profiles, flags - **Auto-install**: `ccs --shell-completion` or `ccs -sc` -### 4. Comprehensive Diagnostics (v4.1+) +### 5. Comprehensive Diagnostics (v4.1+) - **ccs doctor**: Health check for installation, configs, symlinks, delegation - **ccs sync**: Re-sync delegation commands and skills - **ccs update**: Check for updates (v4.1+) -### 5. GLMT Thinking Mode (v3.x, stable experimental) +### 6. Text-Only Output (Phase 02 - CLAUDE.md Compliance) +- **ASCII indicators only**: [OK], [!], [X], [i] (no emoji) +- **TTY-aware colors**: Respects NO_COLOR environment variable +- **Consistent formatting**: Box borders for errors using ╔═╗║╚╝ +- **Cross-platform consistency**: Identical output on all shells + +### 7. GLMT Thinking Mode (v3.x, stable experimental) - **Embedded proxy**: HTTP proxy on localhost:random - **Format conversion**: Anthropic ↔ OpenAI - **Reasoning injection**: Force English, thinking prompts @@ -538,30 +552,37 @@ Claude CLI: Read credentials from instance, execute ## Summary -**CCS Phase 02 Achievements (2025-11-27)**: +**CCS Phase 02 Achievements (2025-11-28)**: +- **npm-First Distribution**: Deprecated native shell installers, all users directed to npm - **Modular Command Architecture**: 6 specialized command handlers with single responsibility principle - **44.6% Main File Reduction**: src/ccs.ts reduced from 1,071 to 593 lines +- **Text-Only Output**: All emoji removed ([!] replaces ⚠️), CLAUDE.md compliance - **Enhanced Maintainability**: Focused modules for version, help, install, doctor, sync, shell-completion - **New Utility Modules**: Cross-platform shell execution and package manager detection - **TypeScript Excellence**: 100% type coverage across all new modules +- **Installation Flow**: Auto-redirection from deprecated shell scripts to npm -**CCS v4.3.2 Achievements**: +**CCS v4.5.0 Overall Achievements**: - **Delegation system**: Complete AI-powered task routing with stream-JSON - **Selective symlinking**: Non-invasive .claude/ directory sharing - **Shell completion**: Enhanced UX with color-coded completions - **Diagnostics**: Comprehensive health checking and auto-recovery +- **npm Package**: Bootstrap-based installation, quality gates (typecheck, lint, format, test) - **Modular architecture**: Clear separation of concerns (auth/, delegation/, glmt/, management/, utils/, commands/, types/) -**Design Principles Maintained**: +**Design Principles (STRICT ENFORCEMENT)**: - **YAGNI**: Only essential features implemented - **KISS**: Simple, readable code without over-engineering - **DRY**: Single source of truth for each concern +- **CLI-First**: All features must have CLI interface +- **No Emojis**: ASCII indicators only per CLAUDE.md **Code Quality**: - **Total LOC**: ~8,477 lines (src/ TypeScript) - **Main File**: 593 lines (44.6% reduction from 1,071 lines) - **Test Coverage**: >90% for critical paths -- **Modularity**: 8 subsystems (main, auth, delegation, glmt, management, utils, commands, types, .claude/) -- **Documentation**: Comprehensive inline comments and external docs +- **Modularity**: 9 subsystems (main, auth, delegation, glmt, management, utils, commands, types, .claude/) +- **Documentation**: Comprehensive inline comments, README.md, 8+ doc files +- **Output Format**: ASCII-only text, TTY-aware colors, NO_COLOR compliant -v4.3.2 demonstrates successful feature expansion (delegation, symlinking, diagnostics) while maintaining core simplicity and zero breaking changes from v3.0. Phase 02 modular command architecture further enhances maintainability and provides a sustainable foundation for future AI-powered development workflow enhancements. +Phase 02 (2025-11-28) completes npm-first transition with native installer deprecation and text-only output compliance. v4.5.0 demonstrates successful feature expansion (delegation, symlinking, diagnostics, modular CLI) while maintaining core simplicity and zero breaking changes from v3.0. Bootstrap-based installers eliminate shell script complexity and provide consistent cross-platform behavior. diff --git a/docs/en/installation.md b/docs/en/installation.md index b1c78baf..fe02657c 100644 --- a/docs/en/installation.md +++ b/docs/en/installation.md @@ -1,5 +1,9 @@ # CCS Installation Guide +> [!WARNING] +> **Native shell installers (curl/irm) are deprecated.** +> Use npm installation for all platforms. Legacy installers will be removed in v5.0. + ## npm Package Installation (Recommended) ### Cross-Platform Installation @@ -34,7 +38,11 @@ npm install -g @kaitranntt/ccs npm install -g @kaitranntt/ccs --force ``` -## One-Liner Installation (Traditional) +## [!] DEPRECATED: One-Liner Installation (Legacy) + +> [!WARNING] +> **These installers are deprecated and will be removed in v5.0.** +> They now auto-redirect to npm installation. Please use npm directly. ### macOS / Linux @@ -46,8 +54,7 @@ curl -fsSL ccs.kaitran.ca/install | bash curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.sh | bash ``` -**Install Location**: -- **All Unix Systems**: `~/.local/bin/ccs` (auto-configures PATH for bash, zsh, fish) +**Note:** Scripts show deprecation warning and automatically run npm installation if Node.js is available. ### Windows PowerShell @@ -59,18 +66,12 @@ irm ccs.kaitran.ca/install.ps1 | iex irm https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.ps1 | iex ``` -**Auto PATH Configuration**: -- Installer detects your shell (bash, zsh, fish) automatically -- Adds `~/.local/bin` to PATH in shell profile if needed -- Idempotent: safe to run multiple times -- Shows reload instructions after install +**Note:** Scripts show deprecation warning and automatically run npm installation if Node.js is available. -**Notes**: -- Unix installer supports both direct execution (`./install.sh`) and piped installation (`curl | bash`) -- Windows installer requires PowerShell 5.1+ (pre-installed on Windows 10+) -- No sudo required on any platform +## [!] DEPRECATED: Git Clone Installation (Legacy) -## Git Clone Installation +> [!WARNING] +> **Git clone installation is deprecated.** Use npm installation instead. ### macOS / Linux @@ -88,7 +89,7 @@ cd ccs .\installers\install.ps1 ``` -**Note**: Works with git worktrees and submodules - the installer detects both `.git` directory and `.git` file. +**Note**: Scripts show deprecation warning and automatically run npm installation if Node.js is available. ## Manual Installation diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md index d2f91214..528ae328 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/troubleshooting.md @@ -2,6 +2,23 @@ > **Note**: CCS has been recently simplified with a 35% code reduction (1,315 → 855 lines) while maintaining all functionality. The troubleshooting steps below apply to the simplified architecture. +## Native Installer Deprecation + +**Issue:** "Why does the curl/irm installer show a deprecation warning?" + +**Cause:** Native shell installers are deprecated in favor of npm installation. + +**Solution:** +```bash +# Uninstall legacy version (if installed via curl/irm) +ccs-uninstall # or: curl -fsSL ccs.kaitran.ca/uninstall | bash + +# Install via npm (recommended) +npm install -g @kaitranntt/ccs +``` + +**Note:** The legacy installer now auto-runs npm install if Node.js is available. + ## npm Installation Issues ### Config File Not Found After npm Install diff --git a/docs/en/usage.md b/docs/en/usage.md index e029d60a..51414945 100644 --- a/docs/en/usage.md +++ b/docs/en/usage.md @@ -103,17 +103,16 @@ Run 'ccs --help' for usage information - Platform-specific guidance - Configuration file location and troubleshooting -**Official Uninstall (Recommended)**: +**Uninstall (Recommended)**: ```bash -# macOS/Linux -curl -fsSL ccs.kaitran.ca/uninstall | bash +# npm (recommended) +npm uninstall -g @kaitranntt/ccs -# Windows PowerShell -irm ccs.kaitran.ca/uninstall | iex +# Legacy uninstallers (for native installs only) +# macOS/Linux: curl -fsSL ccs.kaitran.ca/uninstall | bash +# Windows: irm ccs.kaitran.ca/uninstall | iex ``` -The official uninstaller completely removes CCS including configs and PATH modifications. - **Platform-Specific Locations**: - macOS: `/usr/local/bin/ccs` - Linux: `~/.local/bin/ccs` diff --git a/docs/ja/README.md b/docs/ja/README.md index 982f8e36..2ce4cbe2 100644 --- a/docs/ja/README.md +++ b/docs/ja/README.md @@ -47,10 +47,14 @@ bun add -g @kaitranntt/ccs ```
-代替案：直接インストール（従来型） +[!] 非推奨: ネイティブシェルインストーラー（レガシー）
+> [!WARNING] +> **これらのインストーラーは非推奨であり、将来のバージョンで削除されます。** +> 現在は npm インストールに自動リダイレクトされます。npm を直接使用してください。 + **macOS / Linux** ```bash curl -fsSL ccs.kaitran.ca/install | bash @@ -61,7 +65,7 @@ curl -fsSL ccs.kaitran.ca/install | bash irm ccs.kaitran.ca/install | iex ``` -**注**: 従来型インストールはNode.jsルーティングをバイパスし起動が高速ですが、デプロイ自動化が容易なためnpmを優先します。 +**注**: スクリプトは非推奨の警告を表示し、Node.jsが利用可能な場合は自動的にnpmインストールを実行します。
diff --git a/docs/version-management.md b/docs/version-management.md index 33637f50..da79b023 100644 --- a/docs/version-management.md +++ b/docs/version-management.md @@ -82,12 +82,12 @@ When releasing a new version: - [ ] Update version using `./scripts/bump-version.sh X.Y.Z` - [ ] Review changes: `git diff` - [ ] Run comprehensive tests: `npm test` -- [ ] Test both installation methods if applicable +- [ ] ~~Test both installation methods if applicable~~ (Shell installers DEPRECATED) - [ ] Update CHANGELOG.md with release notes - [ ] Commit changes: `git commit -am "chore: bump version to X.Y.Z"` - [ ] Push: `git push` -- [ ] Verify CloudFlare worker serves updated installer -- [ ] Publish to npm (if npm package updated): `npm publish` +- [ ] ~~Verify CloudFlare worker serves updated installer~~ (Shell installers DEPRECATED) +- [ ] Publish to npm: `npm publish` ## Version Display diff --git a/docs/vi/README.md b/docs/vi/README.md index 03fe36ec..c2bb5c0e 100644 --- a/docs/vi/README.md +++ b/docs/vi/README.md @@ -47,10 +47,14 @@ bun add -g @kaitranntt/ccs ```
-Phương án thay thế: Cài Đặt Trực Tiếp (Truyền thống) +[!] LỖI THỜI: Trình cài đặt shell gốc (Cũ)
+> [!WARNING] +> **Các trình cài đặt này đã lỗi thời và sẽ bị xóa trong phiên bản tương lai.** +> Hiện tại chúng tự động chuyển hướng đến cài đặt npm. Vui lòng sử dụng npm trực tiếp. + **macOS / Linux** ```bash curl -fsSL ccs.kaitran.ca/install | bash @@ -61,7 +65,7 @@ curl -fsSL ccs.kaitran.ca/install | bash irm ccs.kaitran.ca/install | iex ``` -**Lưu ý**: Cài truyền thống bỏ qua Node.js routing để khởi động nhanh hơn, nhưng ưu tiên npm cho dễ dàng tự động hóa triển khai. +**Lưu ý**: Script hiển thị cảnh báo lỗi thời và tự động chạy cài đặt npm nếu Node.js khả dụng.
diff --git a/docs/vi/installation.vi.md b/docs/vi/installation.vi.md index 8502c3e4..66b79e82 100644 --- a/docs/vi/installation.vi.md +++ b/docs/vi/installation.vi.md @@ -1,5 +1,9 @@ # Hướng Dẫn Cài Đặt CCS +> [!WARNING] +> **Trình cài đặt shell gốc (curl/irm) đã lỗi thời.** +> Sử dụng cài đặt npm cho tất cả các nền tảng. Trình cài đặt cũ sẽ bị xóa trong v5.0. + ## Cài Đặt npm Package (Được khuyến nghị) ### Cài Đặt Đa Nền Tảng @@ -34,7 +38,11 @@ npm install -g @kaitranntt/ccs npm install -g @kaitranntt/ccs --force ``` -## Cài Đặt Một Dòng Lệnh (Truyền thống) +## [!] LỖI THỜI: Cài Đặt Một Dòng Lệnh (Cũ) + +> [!WARNING] +> **Các trình cài đặt này đã lỗi thời và sẽ bị xóa trong v5.0.** +> Hiện tại chúng tự động chuyển hướng đến cài đặt npm. Vui lòng sử dụng npm trực tiếp. ### macOS / Linux @@ -46,8 +54,7 @@ curl -fsSL ccs.kaitran.ca/install | bash curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.sh | bash ``` -**Vị Trí Cài Đặt**: -- **Tất Cả Hệ Thống Unix**: `~/.local/bin/ccs` (tự động cấu hình PATH cho bash, zsh, fish) +**Lưu ý**: Script hiển thị cảnh báo lỗi thời và tự động chạy cài đặt npm nếu Node.js khả dụng. ### Windows PowerShell @@ -59,16 +66,7 @@ irm ccs.kaitran.ca/install.ps1 | iex irm https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.ps1 | iex ``` -**Cấu Hình PATH Tự Động**: -- Installer tự động phát hiện shell của bạn (bash, zsh, fish) -- Thêm `~/.local/bin` vào PATH trong shell profile nếu cần -- Idempotent: an toàn khi chạy nhiều lần -- Hiển thị hướng dẫn reload sau khi cài đặt - -**Lưu ý**: -- Installer Unix hỗ trợ cả chạy trực tiếp (`./install.sh`) và cài đặt qua pipe (`curl | bash`) -- Installer Windows yêu cầu PowerShell 5.1+ (đã cài sẵn trên Windows 10+) -- Không cần sudo trên bất kỳ nền tảng nào +**Lưu ý**: Script hiển thị cảnh báo lỗi thời và tự động chạy cài đặt npm nếu Node.js khả dụng. ## Cài Đặt qua Git Clone diff --git a/docs/vi/troubleshooting.vi.md b/docs/vi/troubleshooting.vi.md index 96ce1a49..f738aaa7 100644 --- a/docs/vi/troubleshooting.vi.md +++ b/docs/vi/troubleshooting.vi.md @@ -1,5 +1,22 @@ # Hướng Dẫn Khắc Phục Sự Cố CCS +## Cảnh báo lỗi thời của trình cài đặt gốc + +**Vấn đề:** "Tại sao trình cài đặt curl/irm hiển thị cảnh báo lỗi thời?" + +**Nguyên nhân:** Trình cài đặt shell gốc đã lỗi thời, ưu tiên cài đặt npm. + +**Giải pháp:** +```bash +# Gỡ cài đặt phiên bản cũ (nếu cài qua curl/irm) +ccs-uninstall # hoặc: curl -fsSL ccs.kaitran.ca/uninstall | bash + +# Cài đặt qua npm (khuyến nghị) +npm install -g @kaitranntt/ccs +``` + +**Lưu ý:** Trình cài đặt cũ hiện tự động chạy npm install nếu Node.js khả dụng. + ## Vấn Đề Riêng Của Windows ### PowerShell Execution Policy diff --git a/src/commands/help-command.ts b/src/commands/help-command.ts index 5f45561c..b90b4136 100644 --- a/src/commands/help-command.ts +++ b/src/commands/help-command.ts @@ -102,9 +102,10 @@ export function handleHelpCommand(): void { console.log(''); console.log(colored('Uninstall:', 'yellow')); - console.log(' npm: npm uninstall -g @kaitranntt/ccs'); - console.log(' macOS/Linux: curl -fsSL ccs.kaitran.ca/uninstall | bash'); - console.log(' Windows: irm ccs.kaitran.ca/uninstall | iex'); + console.log(' npm (recommended): npm uninstall -g @kaitranntt/ccs'); + console.log(' Legacy (deprecated):'); + console.log(' macOS/Linux: curl -fsSL ccs.kaitran.ca/uninstall | bash'); + console.log(' Windows: irm ccs.kaitran.ca/uninstall | iex'); console.log(''); console.log(colored('Documentation:', 'cyan'));