1 line
14 KiB
JSON
1 line
14 KiB
JSON
{"repo": "cexll/codex-env", "files": {"README.md": {"8115674a21474fda09a2b139a8af6bbc7d71180b": {"t": 1785674435.586644, "n": 13283, "h": "783bddca9758e7f4", "c": "# Codex Env Launcher (CDE)\n[中文](./README_zh.md)\n\nA production-ready Go CLI tool that manages multiple Codex/OpenAI environment configurations, enabling seamless switching between environments (production, staging, custom providers). CDE acts as a thin wrapper around `codex` with **flag passthrough**, **ANSI-free display management**, and **universal terminal compatibility**.\n\n## ✨ Key Features\n\n### 🎯 **Core Functionality**\n- **Environment Management**: Add, list, remove Codex configurations with interactive selection\n- **Additional Environment Variables**: Configure custom environment variables per environment (e.g., `OPENAI_TIMEOUT`)\n- **Flag Passthrough**: Transparently forward arguments to Codex (`cde --help`, etc.)\n- **Secure API Key Storage**: Hidden terminal input with masked display and proper file permissions\n- **Universal Terminal Support**: ANSI-free display system working across SSH, CI/CD, and all terminal types\n\n### 🖥️ **Advanced UI Features**\n- **Responsive Design**: Adapts to any terminal width (20-300+ columns tested)\n- **4-Tier Progressive Fallback**: Full interactive → Basic interactive → Numbered selection → Headless mode\n- **Smart Content Truncation**: Preserves essential information while preventing overflow\n- **Clean Navigation**: Stateful rendering prevents display stacking during arrow key navigation\n\n### 🔒 **Enterprise-Grade Security**\n- **Command Injection Prevention**: Comprehensive argument validation with shell metacharacter detection\n- **Secure File Operations**: Configuration stored with 600/700 permissions and atomic writes\n- **API Key Protection**: Terminal raw mode input with masked display (first 6 + last 4 chars)\n- **Input Sanitization**: URL validation, name sanitization, and format checking\n\n## 📦 Installation\n\n### Method 1: Go Install (Recommended)\n\n```bash\n# Install the latest version directly\ngo install github.com/cexll/codex-env@latest\n\n# The binary will be installed to $GOPATH/bin/codex-env\n# Add to PATH if not already done:\nexport PATH=$PATH:$(go env GOPATH)/bin\n\n# Verify installation\ncodex-env --version\n```\n\n### Method 2: Build from Source\n\n```bash\ngit clone https://github.com/cexll/codex-env.git\ncd codex-env\ngo build -o cde .\n```\n\n### Install Codex CLI\n\nIf `codex` is not installed, install the official CLI:\n\n```bash\nnpm install -g @openai/codex\n```\n\n### Install to System PATH\n\n```bash\nsudo mv cde /usr/local/bin/\n# Verify installation\ncde --help\n```\n\n## 🚀 Usage\n\n### Basic Commands\n\n#### Interactive Launch\n```bash\ncde # Shows responsive environment selection menu with arrow navigation\n```\n\n#### Launch with Specific Environment\n```bash\ncde --env production # or -e production\ncde -e staging # Launch with staging environment\n```\n\n#### Flag Passthrough Examples\n```bash\ncde auto -e dev -- mcp # Auto-approve with sandbox, run mcp\ncde -- --help # Show codex help (-- explicitly separates flags)\ncde -e staging -- proto # Run proto with staging\n```\n\n### Environment Management\n\n#### Add a new environment:\n```bash\ncde add\n# Interactive prompts for:\n# - Environment name (validated)\n# - API URL (with format validation)\n# - API Key (secure hidden input)\n# - Model (optional, e.g., gpt-5)\n# - Additional environment variables (optional, e.g., OPENAI_TIMEOUT)\n```\n\n#### List all environments:\n```bash\ncde list\n# Output with responsive formatting:\n# Configured environments (3):\n#\n# Name: production\n# URL: https://api.openai.com/v1\n# Model: gpt-5\n# Key: sk-************************************************************\n# Env: OPENAI_TIMEOUT=30s\n# CUSTOM_TIMEOUT=60s\n#\n# Name: staging\n# URL: https://api.openai.com/v1\n# Model: default\n# Key: sk-stg-************************************************************\n```\n\n#### Remove an environment:\n```bash\ncde remove staging\n# Confirmation and secure removal with backup\n```\n\n#### Using Additional Environment Variables:\nWhen adding a new environment, you can configure additional environment variables:\n\n```bash\ncde add\n# Example interactive session:\n# Environment name: kimi-k2\n# Base URL: https://api.moonshot.cn\n# API Key: [secure input]\n# Model: moonshot-v1-32k\n# Additional environment variables (optional):\n# Variable name: OPENAI_TIMEOUT\n# Value for OPENAI_TIMEOUT: 30s\n# Variable name: [press Enter to finish]\n```\n\nThese environment variables will be automatically set when launching Codex with this environment.\n\n### Command Line Interface\n\n```bash\ncde [options] [-- codex-args...]\n\nOptions:\n -e, --env <name> Use specific environment\n -h, --help Show comprehensive help with examples\n\nCommands:\n list List all environments with responsive formatting\n add Add new environment (supports model specification)\n remove <name> Remove environment with confirmation\n auto Auto-approve with sandbox (-a never --sandbox workspace-write)\n\nFlag Passthrough:\n Any arguments after CDE options are passed directly to codex.\n Use '--' to explicitly separate CDE options from codex arguments.\n\nExamples:\n cde Interactive selection and launch\n cde --env prod Launch with 'prod' environment\n cde auto -e dev -- mcp Auto-approve and run mcp\n cde --env staging -- proto Use staging, pass to codex\n cde -- --help Show codex help\n```\n\n## 📁 Configuration\n\n### Configuration File Structure\n\nEnvironments stored in `~/.codex-env/config.json`:\n\n```json\n{\n \"environments\": [\n {\n \"name\": \"production\",\n \"url\": \"https://api.openai.com/v1\",\n \"api_key\": \"sk-xxxxx\",\n \"model\": \"gpt-5\",\n \"env_vars\": {\n \"OPENAI_TIMEOUT\": \"30s\"\n }\n },\n {\n \"name\": \"staging\",\n \"url\": \"https://api.openai.com/v1\",\n \"api_key\": \"sk-staging-xxxxx\",\n \"model\": \"default\",\n \"env_vars\": {\n \"OPENAI_TIMEOUT\": \"30s\"\n }\n }\n ],\n \"settings\": {\n \"validation\": {\n \"strict_validation\": false\n }\n }\n}\n```\n\n### Environment Variables\n\n**Additional Environment Variables Support:**\nCDE supports configuring additional environment variables for each environment. These variables are automatically set when launching Codex with the selected environment.\n\n**Common Use Cases:**\n- `OPENAI_TIMEOUT`: Set custom timeout values for API requests (e.g., `30s`)\n- Any custom environment variables required by your Codex setup\n\n**Model Validation Configuration:**\n- `CDE_MODEL_PATTERNS`: Comma-separated custom regex patterns for model validation\n- `CDE_MODEL_STRICT`: Set to \"false\" for permissive mode\n\n## 🏗️ Architecture\n\n### Core Components (4 Files)\n\n- **`main.go`** (580+ lines): CLI interface, **flag passthrough system**, model validation\n- **`config.go`** (367 lines): Atomic file operations, backup/recovery, validation\n- **`ui.go`** (1000+ lines): **ANSI-free display management**, responsive UI, 4-tier fallback\n- **`launcher.go`** (174 lines): Process execution with argument forwarding\n\n### Key Design Patterns\n\n**Flag Passthrough System**: Two-phase argument parsing separates CDE flags from Codex arguments, enabling transparent command forwarding with security validation.\n\n**ANSI-Free Display Management**: Universal terminal compatibility using:\n- **DisplayState**: Tracks screen content and manages stateful updates\n- **TextPositioner**: Cursor control using carriage return and padding (no ANSI)\n- **LineRenderer**: Stateful menu rendering with differential updates\n\n**4-Tier Progressive Fallback**:\n1. **Full Interactive**: Stateful rendering with arrow navigation and ANSI enhancements\n2. **Basic Interactive**: ANSI-free display with arrow key support\n3. **Numbered Selection**: Fallback for limited terminals\n4. **Headless Mode**: Automated mode for CI/CD environments\n\n## 🔒 Security Implementation\n\n### Multi-Layer Security\n- **Command Injection Prevention**: Comprehensive argument validation with shell metacharacter detection\n- **Secure File Operations**: Atomic writes with proper permissions (600 for files, 700 for directories)\n- **API Key Protection**: Terminal raw mode input, masked display, never logged\n- **Input Validation**: URL validation, name sanitization, API key format checking\n- **Process Isolation**: Clean environment variable handling with secure argument forwarding\n\n### Security Validation\n- **Timing Attack Resistance**: Secure comparison operations\n- **Memory Safety**: Proper cleanup and bounded operations\n- **Environment Sanitization**: Clean variable injection without exposure\n\n## 🧪 Testing & Quality\n\n### Comprehensive Test Coverage (95%+)\n\n```bash\n# Run full test suite\ngo test -v ./...\n\n# Security-specific tests\ngo test -v -run TestSecurity\n\n# Performance benchmarks\ngo test -bench=. -benchmem\n\n# Coverage analysis\ngo test -coverprofile=coverage.out\ngo tool cover -html=coverage.out\n```\n\n### Test Categories\n- **Unit Tests**: Core functionality (parseArguments, formatSingleLine, etc.)\n- **Integration Tests**: End-to-end workflows and cross-platform compatibility\n- **Security Tests**: Command injection prevention, file permissions, input validation\n- **Terminal Compatibility**: SSH, CI/CD, terminal emulators (iTerm, VS Code, etc.)\n- **Performance Tests**: Sub-microsecond operations, memory efficiency\n- **Regression Tests**: Display stacking prevention, layout overflow protection\n\n### Quality Metrics\n- **Overall Quality Score**: 96/100 (automated validation)\n- **Test Coverage**: 95%+ across all components\n- **Performance**: Sub-microsecond operations, minimal memory overhead\n- **Security**: Zero vulnerabilities, comprehensive threat coverage\n- **Compatibility**: 100% backward compatibility, universal terminal support\n\n## 🛠️ Development\n\n### Build and Test\n\n```bash\n# Development build\ngo build -o cde .\n\n# Run comprehensive test suite\nmake test # or: go test -v ./...\nmake test-coverage # HTML coverage report\nmake test-security # Security-specific tests\nmake bench # Performance benchmarks\n\n# Code quality\nmake quality # fmt + vet + test\nmake fmt # Format code\nmake vet # Static analysis\n```\n\n### Project Structure\n\n```\n├── main.go # CLI interface and flag passthrough system\n├── config.go # Configuration management with atomic operations\n├── ui.go # ANSI-free display management and responsive UI\n├── launcher.go # Process execution with argument forwarding\n├── go.mod # Go module definition\n├── go.sum # Dependency checksums\n├── CLAUDE.md # Development documentation\n├── README.md # User documentation\n└── Tests:\n ├── *_test.go # Comprehensive unit tests\n ├── integration_test.go # End-to-end workflows\n ├── security_test.go # Security validation\n ├── terminal_display_fix_test.go # Display management\n ├── ui_layout_test.go # Responsive layout\n └── display_stacking_fix_test.go # Navigation behavior\n```\n\n## 📋 Requirements\n\n- **Go 1.21+** (for building from source)\n- **Claude Code CLI** must be installed and available in PATH as `claude`\n- **Terminal**: Any terminal emulator (ANSI support optional but enhanced)\n\n## 🚀 Migration Guide\n\n### From Previous Versions\nThis enhanced version maintains full backward compatibility. Existing configuration files in `~/.claude-code-env/config.json` work immediately without modification.\n\n### New Features Available\n- **Additional Environment Variables**: Configure custom environment variables like `ANTHROPIC_SMALL_FAST_MODEL`\n- **Flag Passthrough**: Start using `cde -r`, `cde --help`, etc.\n- **Enhanced UI**: Enjoy responsive design and clean navigation\n- **Universal Compatibility**: Works consistently across all terminal types\n- **Enhanced Security**: Benefit from command injection prevention\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make changes following KISS principles and existing patterns\n4. Add comprehensive tests for new functionality\n5. Run `make test` to ensure all tests pass\n6. Run `make quality` for code quality checks\n7. Submit a pull request with detailed description\n\n### Development Principles\n1. **KISS Principle**: Simple, direct implementations\n2. **Security First**: All operations must be secure by design\n3. **Universal Compatibility**: Features must work across all platforms\n4. **Comprehensive Testing**: 95%+ test coverage required\n5. **Performance Focus**: Sub-microsecond operations preferred\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with **Claude Code** integration\n- Powered by **Go standard library** + `golang.org/x/term`\n- Designed with **KISS principles** and **universal compatibility**\n- Tested across **multiple platforms** and **terminal environments**\n\n---\n\n**Claude Code Environment Switcher**: Production-ready, secure, and universally compatible CLI tool for managing Claude Code environments with transparent flag passthrough and intelligent display management.\n"}}}} |