mirror of
https://github.com/hanzoai/opencode-openai-codex-auth.git
synced 2026-09-24 17:01:02 +00:00
Numman AliandHanzo Dev
7dae285752
## 🎯 Overview Complete TypeScript rewrite with comprehensive testing, modular architecture, and enhanced user experience. Adds 9 pre-configured model variants matching Codex CLI presets and a beautiful OAuth success page. ## ✨ New Features ### Configuration System - **9 Model Variants**: Pre-configured reasoning levels (Low/Medium/High) for both gpt-5-codex and gpt-5, plus Minimal variants - **Full Config Example**: `config/full-opencode.json` with all variants ready to use - **Minimal Config Example**: `config/minimal-opencode.json` for basic setup - **Config Documentation**: Comprehensive guide in `config/README.md` ### OAuth Enhancement - **Animated Success Page**: Beautiful terminal-style UI with matrix rain effect, animated checkmark, and glowing effects - **Interactive Elements**: Mouse-responsive matrix rain and parallax effects - **Professional Branding**: OpenCode logo with pulse animations ### Developer Experience - **TypeScript Rewrite**: Complete migration from .mjs to .ts with strict typing - **93 Comprehensive Tests**: Full test coverage using Vitest - **Modular Architecture**: 10 focused helper functions, each < 40 lines - **Centralized Constants**: All magic values in `lib/constants.ts` - **CI/CD Pipeline**: GitHub Actions workflow for automated testing ### Documentation - **AGENTS.md**: Complete guide for AI assistants maintaining the codebase - **Enhanced README**: Updated with new configuration options and examples - **Inline JSDoc**: Comprehensive documentation for all public functions ## 🏗️ Technical Changes ### Architecture Improvements - Extracted 10 focused helper functions from monolithic fetch() - Centralized all constants and error messages - Separated concerns: auth, browser, codex, server, etc. - Type-safe discriminated unions for result types ### Build System - TypeScript compilation with declarations and source maps - Automatic HTML asset copying in build process - Test files excluded from distribution bundle - Clean dist/ output with only production code ### Testing Infrastructure - Vitest test runner with UI mode - 93 tests across 7 test files - Mock-based testing for external dependencies - Coverage reporting capability ## 📁 New Structure ``` opencode-openai-codex-auth/ ├── index.ts # Main plugin (TypeScript) ├── lib/ │ ├── auth.ts # OAuth logic │ ├── browser.ts # Platform-specific browser opening │ ├── codex.ts # Codex instructions │ ├── server.ts # OAuth callback server │ ├── fetch-helpers.ts # 10 focused helpers │ ├── constants.ts # All magic values │ ├── types.ts # TypeScript types │ ├── oauth-success.html # Animated success page │ └── ... ├── config/ │ ├── full-opencode.json # Complete config with variants │ ├── minimal-opencode.json # Basic config │ └── README.md # Config docs ├── test/ # 93 comprehensive tests ├── AGENTS.md # AI maintenance guide └── tsconfig.json # TypeScript config ``` ## 🔄 Migration Notes ### Breaking Changes - Plugin now requires TypeScript compilation (dist/ folder) - Configuration structure enhanced (backward compatible) - OAuth success page replaces plain HTML response ### Upgrade Path 1. Use new config from `config/full-opencode.json` for best experience 2. Or continue with minimal config (uses plugin defaults) 3. Rebuild plugin: `npm run build` ## 📊 Metrics - **Lines of Code**: Modular design with functions < 70 lines - **Test Coverage**: 93 tests covering all functionality - **Type Safety**: Strict TypeScript with no `any` types - **Dependencies**: Still minimal (only @openauthjs/openauth) - **Model Variants**: 9 pre-configured options for users ## 🎨 User Experience - **Codex CLI Parity**: Match official CLI reasoning presets - **Beautiful OAuth**: Professional animated success page - **Clear Documentation**: Step-by-step guides and examples - **Flexible Config**: From minimal to comprehensive setups Co-authored-by: Hanzo Dev <[email protected]>
106 lines
3.2 KiB
Markdown
106 lines
3.2 KiB
Markdown
# Test Suite
|
|
|
|
This directory contains the comprehensive test suite for the OpenAI Codex OAuth plugin.
|
|
|
|
## Test Structure
|
|
|
|
```
|
|
test/
|
|
├── README.md # This file
|
|
├── auth.test.ts # OAuth authentication tests
|
|
├── config.test.ts # Configuration parsing tests
|
|
├── logger.test.ts # Logging functionality tests
|
|
├── request-transformer.test.ts # Request transformation tests
|
|
└── response-handler.test.ts # Response handling tests
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
# Run all tests once
|
|
npm test
|
|
|
|
# Watch mode (re-run on file changes)
|
|
npm run test:watch
|
|
|
|
# Visual test UI
|
|
npm run test:ui
|
|
|
|
# Generate coverage report
|
|
npm run test:coverage
|
|
```
|
|
|
|
## Test Coverage
|
|
|
|
### auth.test.ts (16 tests)
|
|
Tests OAuth authentication functionality:
|
|
- State generation and uniqueness
|
|
- Authorization input parsing (URL, code#state, query string formats)
|
|
- JWT decoding and payload extraction
|
|
- Authorization flow creation with PKCE
|
|
- URL parameter validation
|
|
|
|
### config.test.ts (13 tests)
|
|
Tests configuration parsing and merging:
|
|
- Global configuration application
|
|
- Per-model configuration overrides
|
|
- Mixed configuration (global + per-model)
|
|
- Default values and fallbacks
|
|
- Reasoning effort normalization (minimal → low for codex)
|
|
- Lightweight model detection (nano, mini)
|
|
|
|
### request-transformer.test.ts (30 tests)
|
|
Tests request body transformations:
|
|
- Model name normalization (all variants → gpt-5 or gpt-5-codex)
|
|
- Input filtering (removing stored conversation history)
|
|
- Tool remap message injection
|
|
- Reasoning configuration application
|
|
- Text verbosity settings
|
|
- Encrypted reasoning content inclusion
|
|
- Unsupported parameter removal
|
|
|
|
### response-handler.test.ts (10 tests)
|
|
Tests SSE to JSON conversion:
|
|
- Content-type header management
|
|
- SSE stream parsing (response.done, response.completed)
|
|
- Malformed JSON handling
|
|
- Empty stream handling
|
|
- Status preservation
|
|
|
|
### logger.test.ts (5 tests)
|
|
Tests logging functionality:
|
|
- LOGGING_ENABLED constant
|
|
- logRequest function parameter handling
|
|
- Complex data structure support
|
|
|
|
## Test Philosophy
|
|
|
|
1. **Comprehensive Coverage**: Each module has extensive tests covering normal cases, edge cases, and error conditions
|
|
2. **Fast Execution**: All tests run in < 250ms
|
|
3. **No External Dependencies**: Tests use mocked data and don't make real API calls
|
|
4. **Type Safety**: All tests are written in TypeScript with full type checking
|
|
|
|
## CI/CD Integration
|
|
|
|
Tests automatically run in GitHub Actions on:
|
|
- Every push to main
|
|
- Every pull request
|
|
|
|
The CI workflow tests against multiple Node.js versions (18.x, 20.x, 22.x) to ensure compatibility.
|
|
|
|
## Adding New Tests
|
|
|
|
When adding new functionality:
|
|
|
|
1. Create or update the relevant test file
|
|
2. Follow the existing pattern using vitest's `describe` and `it` blocks
|
|
3. Ensure tests are isolated and don't depend on external state
|
|
4. Run `npm test` to verify all tests pass
|
|
5. Run `npm run typecheck` to ensure TypeScript types are correct
|
|
|
|
## Example Configurations
|
|
|
|
See the `config/` directory for working configuration examples:
|
|
- `minimal-opencode.json`: Simplest setup with defaults
|
|
- `full-opencode.json`: Complete example with all model variants
|