ccman 0.1.2 → 2.0.0

package/.github/workflows/release.yml

@@ -10,7 +10,7 @@ jobs:
   release:
     name: Build, Test and Release
     runs-on: ubuntu-latest
-    
+
     permissions:
       contents: write  # 创建 release
       id-token: write  # NPM 发布
@@ -26,7 +26,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.1
+          version: 7.33.7
 
       # 3. 设置 Node.js
       - name: Setup Node.js
@@ -39,7 +39,7 @@ jobs:
       # 4. 安装依赖和构建
       - name: Install and Build
         run: |
-          pnpm install
+          pnpm install --no-frozen-lockfile
           pnpm run lint
           pnpm run build
 
@@ -66,7 +66,7 @@ jobs:
           token: ${{ secrets.NPM_TOKEN }}
           access: public
 
-      # 8. 创建 GitHub Release  
+      # 8. 创建 GitHub Release
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
@@ -96,4 +96,4 @@ jobs:
           draft: false
           prerelease: ${{ contains(github.ref, '-beta') || contains(github.ref, '-alpha') || contains(github.ref, '-rc') }}
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/CLAUDE.md

@@ -4,212 +4,273 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-CCM (Claude Code Manager) is a TypeScript-based command-line tool for managing Claude Code API configurations. It provides structured, modular environment management with **safe shell integration** through independent configuration files.
+CCM (Claude Code Manager) 是一个 TypeScript 命令行工具，用于管理 Claude Code API 配置。新架构直接修改 `~/.claude/settings.json` 文件实现配置切换，无需 shell 集成。
 
-## Architecture
+## 新架构设计 (v2.0.0)
 
-### Core Modules
-- **src/types/index.ts**: TypeScript type definitions for all interfaces
-- **src/config/ConfigManager.ts**: Core configuration management with JSON storage
-- **src/config/EnvironmentManager.ts**: High-level environment group operations
-- **src/shell/ShellManager.ts**: Safe shell configuration file management using ..ccmanrc approach
-- **src/cli.ts**: Command-line interface with Commander.js and unified interaction logic
+### 核心理念
+- **直接配置修改**: 直接修改 `~/.claude/settings.json` 实现配置切换
+- **多供应商支持**: 在 `~/.ccman/providers/` 目录存储多个供应商配置
+- **零 shell 依赖**: 无需修改 shell 配置文件，立即生效
+- **安全备份**: 每次切换前自动备份当前配置
 
-### Project Structure
+### 目录结构
 ```
-src/
-├── types/           # TypeScript type definitions
-├── config/          # Configuration management modules  
-├── shell/           # Shell integration modules
-├── utils/           # Utility functions (future)
-├── cli.ts           # CLI entry point with performUseEnvironment() shared function
-└── index.ts         # Module exports
+~/.ccman/
+├── config.json              # CCM 主配置文件
+├── providers/               # 供应商配置目录
+│   ├── anthropic.json      # Anthropic 官方配置
+│   ├── packycode.json      # Packycode 配置
+│   └── custom.json         # 其他自定义配置
+└── backups/                # 配置备份目录（未来功能）
 ```
 
-## Key Features Implemented
-
-### 1. Safe Shell Integration Architecture
-- **Independent .ccmanrc file**: `~/.ccman/.ccmanrc` contains all environment variables
-- **Minimal shell reference**: Single line added to `.bashrc`/`.zshrc` to source .ccmanrc
-- **Non-invasive approach**: User's shell config remains largely untouched
-- **Easy cleanup**: Remove reference line and delete .ccmanrc file
-
-### 2. Interactive Source Control
-- After environment switching, user chooses source method:
-  - **Manual**: User manually sources or restarts terminal (recommended)
-  - **Auto-source**: Tool attempts automatic sourcing with risk warnings
-
-### 3. Unified Use Logic
-- `performUseEnvironment()` function provides consistent behavior across:
-  - `add` command's "set as current" flow
-  - Standalone `use` command
-  - `config` command's switch environment option
-
-### 4. Complete Interactive Workflows
-- **config command**: Full menu-driven interface for all operations
-- **add command**: Interactive API key input + use confirmation + source choice
-- **Consistent interactions**: All use operations have identical user experience
-
-## Current Environment Variables
+### 项目结构
+```
+src/
+├── types/                  # TypeScript 类型定义
+├── core/                   # 核心模块
+│   ├── CCMConfigManager.ts     # CCM 配置管理
+│   └── ClaudeConfigManager.ts  # Claude 配置管理
+├── providers/              # 供应商管理
+│   └── ProviderManager.ts      # 供应商业务逻辑
+├── cli.ts                  # CLI 入口点
+└── index.ts               # 模块导出
+```
 
-The tool manages these Claude Code environment variables:
-- `ANTHROPIC_BASE_URL`: API base URL
-- `ANTHROPIC_AUTH_TOKEN`: API authentication token
+## 配置文件结构
+
+### CCM 主配置 (~/.ccman/config.json)
+```json
+{
+  "currentProvider": "anthropic",
+  "claudeConfigPath": "~/.claude/settings.json",
+  "providers": {
+    "anthropic": {
+      "name": "Anthropic Official",
+      "configFile": "anthropic.json",
+      "lastUsed": "2025-01-15T10:30:00.000Z"
+    }
+  },
+  "metadata": {
+    "version": "2.0.0",
+    "createdAt": "2025-01-10T08:00:00.000Z",
+    "updatedAt": "2025-01-15T10:30:00.000Z"
+  }
+}
+```
 
-*Note: Updated from previous CLAUDE_API_BASE_URL and ANTHROPIC_API_KEY*
+### 供应商配置 (~/.ccman/providers/anthropic.json)
+```json
+{
+  "name": "Anthropic Official",
+  "description": "Official Anthropic API",
+  "config": {
+    "env": {
+      "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
+      "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
+      "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
+    },
+    "permissions": {
+      "allow": [],
+      "deny": []
+    },
+    "apiKeyHelper": "echo 'sk-xxx'"
+  },
+  "metadata": {
+    "createdAt": "2025-01-10T08:00:00.000Z",
+    "updatedAt": "2025-01-15T10:30:00.000Z",
+    "usageCount": 25
+  }
+}
+```
 
-## Common Commands
+## 命令使用
 
-### Development
+### 开发命令
 ```bash
-npm run build         # Compile TypeScript to dist/
-npm run dev           # Run CLI in development mode with tsx
-npm start             # Run compiled CLI
-npm run clean         # Remove dist/ directory
-npm run lint          # Run ESLint on TypeScript files (requires config)
+npm run build         # 编译 TypeScript
+npm run dev           # 开发模式运行
+npm start             # 运行编译后的程序
+npm run clean         # 清理构建文件
+npm run lint          # 代码检查
 ```
 
-### Basic Usage
+### 基础使用（精简版）
 ```bash
-ccman ls                # List all environment groups (* = current)
-ccman add <name> <url>  # Add environment group with interactive flow
-ccman use <name>        # Switch environment with source interaction
-ccman remove <name>     # Delete environment group
-ccman current           # Show current environment
-ccman status            # Show CCM statistics
-ccman config            # Interactive configuration menu
-ccman clear             # Clear all environments and shell integration (DESTRUCTIVE)
+# 核心命令（6个）
+ccman                             # 交互式菜单（默认入口）
+ccman ls                          # 智能列表显示（合并原status信息）
+ccman ls --current                # 显示当前供应商详情（替代原current）
+ccman ls --brief                  # 简洁模式显示
+ccman add <id> <name> <url> [key] # 添加供应商配置
+ccman use <id>                    # 切换到指定供应商
+ccman rm <id>                     # 删除供应商配置（别名：remove）
+ccman clear                       # 清除所有配置（别名：reset）
 ```
 
-### Advanced Features
+### 命令详解
 ```bash
-ccman env               # Generate shell script for manual sourcing
-ccman test [name]       # Test environment configuration
-ccman add <name> <url> --no-auto-write    # Add without shell integration
-ccman use <name> --no-auto-write          # Switch without shell integration
-ccman use <name> --auto-source            # Force auto-source with risk warning
+# 默认交互模式 - 最直观的入口
+ccman                    # 进入菜单，包含所有操作（添加/切换/更新/删除/状态）
+
+# 智能列表命令 - 整合了多种信息显示
+ccman ls                 # 显示所有供应商 + 系统状态信息
+ccman ls --current       # 仅显示当前供应商的详细信息  
+ccman ls --brief         # 简洁模式，仅显示供应商名称和ID
+
+# 快速操作命令 - 适合脚本和熟练用户
+ccman add <id> <name> <url> [key] -d "description"  # 添加时指定描述
+ccman use <id>                                      # 快速切换
+ccman rm <id>                                       # 快速删除
+ccman clear                                         # 重置所有配置
 ```
 
-## Implementation Details
-
-### 1. Environment Group Management
-- Add/remove/switch between environment groups
-- Each group contains: name, baseUrl, apiKey, timestamps
-- Automatic validation of URLs and required fields
-- Interactive API key input if not provided
-
-### 2. Shell Integration Process
-1. **Write .ccmanrc**: Environment variables written to `~/.ccman/.ccmanrc`
-2. **Add reference**: Shell config updated to source .ccmanrc if not already present
-3. **User choice**: Interactive prompt for sourcing method
-4. **Auto-source**: Optional automatic sourcing with error handling
-
-### 3. Type Safety Implementation
-- Full TypeScript implementation with strict typing
-- Interfaces for all data structures and operations:
-  - `ClaudeEnv`: Environment configuration
-  - `ShellEnvVars`: Environment variables with correct naming
-  - `AddEnvOptions`: Add operation parameters
-  - `ShellWriteResult`: Shell operation results
-- Compile-time error checking
-
-### 4. Interactive CLI Features
-- Inquirer.js for consistent prompts
-- Colored output with chalk
-- Confirmation prompts for destructive operations
-- Menu-driven configuration interface
-- Progress feedback and error handling
-
-## Configuration Storage
-
-- Config directory: `~/.ccman/`
-- Main config: `~/.ccman/config.json`
-- Environment variables: `~/.ccman/.ccmanrc`
-- Structure includes environments, current selection, and global settings
-
-## Shell Integration Technical Details
-
-### File Locations
-- **Configuration**: `~/.ccman/.ccmanrc` - Contains current environment variables
-- **Shell reference**: Added to `.bashrc`, `.zshrc`, or `config.fish`
-- **Detection order**: zsh → bash → fish → fallback
-
-### Shell Reference Format
-```bash
-# CCM (Claude Code Manager) - Auto Generated Reference
-# This line sources CCM environment variables from /home/user/.ccman/.ccmanrc
-[ -f "/home/user/.ccman/.ccmanrc" ] && source "/home/user/.ccman/.ccmanrc"
-# End CCM Reference
+## 核心类型定义
+
+### ClaudeSettings
+Claude settings.json 的标准结构
+```typescript
+interface ClaudeSettings {
+  env: {
+    ANTHROPIC_AUTH_TOKEN: string;
+    ANTHROPIC_BASE_URL: string;
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC?: number;
+  };
+  permissions: { allow: string[]; deny: string[]; };
+  apiKeyHelper: string;
+}
 ```
 
-### .ccmanrc File Format
+### ProviderConfig
+供应商配置结构
+```typescript
+interface ProviderConfig {
+  name: string;
+  description: string;
+  config: ClaudeSettings;
+  metadata: {
+    createdAt: string;
+    updatedAt: string;
+    usageCount: number;
+  };
+}
+```
+
+## 关键特性
+
+### 1. 直接配置修改
+- 直接读写 `~/.claude/settings.json`
+- **选择性覆盖**: 只修改CCM管理的key，保留用户其他配置
+- 无需重启终端或 source 任何文件
+- 配置切换立即生效
+
+#### CCM管理的配置项
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "...",       // ✅ CCM管理
+    "ANTHROPIC_BASE_URL": "...",         // ✅ CCM管理  
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1  // ✅ CCM管理
+  },
+  "permissions": {
+    "allow": [],                         // ✅ CCM管理
+    "deny": []                           // ✅ CCM管理
+  },
+  "apiKeyHelper": "..."                  // ✅ CCM管理
+}
+```
+
+#### 用户配置保护
+- 保留所有其他用户自定义配置项
+- 保留 `env` 中其他环境变量  
+- 保留 `permissions` 中其他权限设置
+- 保留所有非CCM管理的顶级配置项
+
+### 2. 自动备份机制
+- 每次切换前自动备份当前配置
+- 备份文件带时间戳，便于恢复
+- 防止配置丢失和冲突
+
+### 3. 交互式界面
+- 使用 inquirer.js 提供友好的交互体验
+- 彩色输出和进度反馈
+- 确认提示防止误操作
+
+### 4. 类型安全
+- 完整的 TypeScript 类型定义
+- 编译时错误检查
+- 严格的接口约束
+
+## 安全注意事项
+
+### 🚨 开发时的重要限制
+
+**绝对禁止修改以下文件（会导致系统不可用）:**
+- `~/.ccman/config.json` - 现有历史配置文件
+- `~/.claude/settings.json` - Claude Code 配置文件
+
+**开发时的安全做法:**
+1. **使用测试目录**: 开发时使用 `~/.ccman-dev/` 或其他测试目录
+2. **配置隔离**: 通过环境变量指定不同的配置路径
+3. **备份验证**: 修改前确保备份机制正常工作
+4. **分步测试**: 先测试读取，再测试写入功能
+
+### 开发环境配置
 ```bash
-# CCM (Claude Code Manager) Environment Variables - Auto Generated
-# Generated at: 2025-08-06 11:45:30
-# Environment: production
-export ANTHROPIC_BASE_URL="https://api.anthropic.com"
-export ANTHROPIC_AUTH_TOKEN="your-api-key"
-# End CCM Environment Variables
+# 设置开发环境配置路径
+export CCM_CONFIG_DIR="~/.ccman-dev"
+export CLAUDE_CONFIG_PATH="~/.claude/settings-dev.json"
+
+# 或在代码中使用环境变量
+const configDir = process.env.CCM_CONFIG_DIR || path.join(os.homedir(), '.ccman');
 ```
 
-## Build Process
-
-1. TypeScript compilation targets ES2020 with CommonJS modules
-2. Output goes to `dist/` directory with source maps
-3. CLI entry point is `dist/cli.js` with proper shebang
-4. Supports both development (`tsx`) and production (`node`) execution
-
-## Code Organization
-
-### CLI Structure (`src/cli.ts`)
-- **performUseEnvironment()**: Shared function for consistent use behavior across commands
-- **Command definitions**: Using Commander.js with proper option handling
-- **Interactive prompts**: Inquirer.js integration for user input
-- **Error handling**: Consistent error reporting and process exit codes
-
-### Shell Manager (`src/shell/ShellManager.ts`)
-- **.ccmanrc management**: Independent file creation and updates
-- **Shell reference management**: Minimal invasive approach
-- **Auto-source capability**: Subprocess execution with error handling
-- **Multi-shell support**: bash, zsh, fish detection and handling
-
-### Environment Manager (`src/config/EnvironmentManager.ts`)
-- **High-level operations**: Add, remove, update, switch environments
-- **Shell integration coordination**: Works with ShellManager for safe updates
-- **Validation**: URL validation, environment name checking
-- **Statistics**: Usage tracking and reporting
-
-## Recent Major Changes
-
-1. **Shell Architecture Redesign**: From direct modification to .ccmanrc + reference approach
-2. **Environment Variable Renaming**: Updated to ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN
-3. **Interactive Source Control**: Added user choice for manual vs automatic sourcing
-4. **Unified Use Logic**: Single function for consistent behavior across all use scenarios
-5. **Time Format Improvement**: Human-readable timestamps instead of ISO format
-6. **Enhanced config Command**: Complete menu-driven interface for all operations
-7. **Clear All Functionality**: Added clearAll command for complete CCM reset with confirmation
-
-## Testing Approach
-
-- Manual testing of CLI interactions
-- Verification of file system operations
-- Shell integration testing across different shells  
-- Error condition handling validation
-- User experience flow testing
-
-## Important Notes for Development
-
-- **Always test shell integration**: Verify .ccmanrc creation and shell reference addition
-- **Test interactive flows**: Ensure prompts work correctly in different scenarios
-- **Validate file operations**: Check permissions and error handling
-- **Cross-shell compatibility**: Test with bash, zsh, and fish when possible
-- **User experience focus**: Prioritize clear messaging and helpful guidance
-
-## Future Enhancement Areas
-
-- Configuration validation and migration
-- Backup and restore functionality
-- Environment templates or presets
-- Integration with external credential stores
-- Enhanced error reporting and diagnostics
-- Network connectivity testing for environments
+## 构建和部署
+
+### TypeScript 编译
+- 目标: ES2020, CommonJS 模块
+- 输出: `dist/` 目录，包含源映射
+- CLI 入口: `dist/cli.js` 带正确的 shebang
+
+### 依赖管理
+- 使用 pnpm 管理依赖
+- 包含所有必要的类型声明
+- 严格的版本控制
+
+## 测试方法
+
+### 功能测试
+- CLI 命令交互测试
+- 文件系统操作验证
+- 配置切换流程测试
+- 错误处理验证
+
+### 安全测试
+- 备份机制验证
+- 权限检查
+- 配置文件完整性
+- 回滚功能测试
+
+## 未来改进
+
+### 计划功能
+- 配置模板和预设
+- 批量配置管理
+- 网络连接测试
+- 配置迁移工具
+- 增强的错误诊断
+
+### 架构优化
+- 插件化供应商支持
+- 配置验证和修复
+- 更好的备份策略
+- 性能优化
+
+## 开发注意事项
+
+- **测试优先**: 修改任何配置管理逻辑前先测试
+- **备份验证**: 确保每次操作都有可靠的备份
+- **用户体验**: 提供清晰的反馈和错误信息
+- **向后兼容**: 考虑现有用户的配置迁移
+- **安全第一**: 绝不能破坏用户的现有配置