feat: Major TypeScript rewrite with enhanced configuration and OAuth UI

[numman-ali]

🎯 Overview

This PR represents a complete TypeScript rewrite of the plugin with comprehensive testing, modular architecture, and significantly enhanced user experience. The plugin now offers 9 pre-configured model variants matching Codex CLI presets and features a beautiful animated OAuth success page.

✨ What's New

🎨 Enhanced User Experience

9 Model Variants (Codex CLI Parity)

Users can now choose from pre-configured reasoning levels:

• GPT 5 Codex: Low, Medium, High
• GPT 5: Minimal, Low, Medium, High
• gpt-5-mini and gpt-5-nano (for compatibility)

All variants appear in the opencode model selector with optimal settings for each reasoning level.

Beautiful OAuth Success Page

• Animated UI: Terminal-style interface with matrix rain background
• Interactive Effects: Mouse-responsive matrix rain and parallax
• Professional Branding: OpenCode logo with pulse animations and glowing effects
• Smooth Animations: Checkmark draw, fade-ins, and gradient shifts

🏗️ Technical Improvements

TypeScript Rewrite

• Complete migration from .mjs to .ts with strict typing
• No any types - fully type-safe codebase
• Comprehensive type definitions in lib/types.ts

Modular Architecture

• 10 Focused Helper Functions: Each < 40 lines for maintainability
• Centralized Constants: All magic values in lib/constants.ts
• Clear Separation of Concerns: auth, browser, codex, server, etc.
• 7-Step Fetch Flow: Well-documented and easy to follow

Comprehensive Testing

• 93 Tests: Covering all functionality
• 7 Test Files: Organized by module
• Vitest Framework: Modern testing with UI mode
• High Coverage: All critical paths tested

Enhanced Documentation

• AGENTS.md: 568-line guide for AI assistants maintaining the codebase
• config/README.md: Complete configuration documentation
• Enhanced README: Updated with new features and clear examples
• Inline JSDoc: Comprehensive documentation for all public functions

📦 Configuration System

Full Configuration (config/full-opencode.json)

Ready-to-use configuration with all 9 model variants. Users can copy this directly to their opencode config for the complete experience.

Features:

• Provider-level defaults
• Model-specific overrides
• Optimal reasoning/verbosity for each variant
• Clear naming: "GPT 5 Codex Low (ChatGPT Subscription)"

Minimal Configuration (config/minimal-opencode.json)

Simple setup for users who want basic functionality with plugin defaults.

📊 Changes by Category

New Files (Major Additions)

Configuration & Docs:

• config/full-opencode.json - Complete configuration example
• config/minimal-opencode.json - Minimal configuration example
• config/README.md - Configuration documentation
• AGENTS.md - AI maintenance guide (568 lines)
• assets/opencode-logo-ornate-dark.svg - Branding asset

Core TypeScript:

• index.ts - Main plugin entry (from index.mjs)
• lib/types.ts - Comprehensive type definitions
• lib/constants.ts - Centralized constants
• lib/fetch-helpers.ts - 10 focused helper functions
• lib/browser.ts - Platform-specific browser opening
• lib/oauth-success.html - Animated OAuth success page (22KB)

Testing:

• test/auth.test.ts - 16 tests for OAuth logic
• test/browser.test.ts - 4 tests for platform detection
• test/config.test.ts - 13 tests for configuration
• test/fetch-helpers.test.ts - 15 tests for helpers
• test/logger.test.ts - 5 tests for logging
• test/request-transformer.test.ts - 30 tests for transformations
• test/response-handler.test.ts - 10 tests for SSE conversion
• test/README.md - Testing documentation
• vitest.config.ts - Vitest configuration

CI/CD:

• .github/workflows/ci.yml - GitHub Actions workflow

Build:

• tsconfig.json - TypeScript configuration

Modified Files

Core:

• package.json - Updated scripts, added devDependencies for TypeScript/Vitest
• .gitignore - Added TypeScript build artifacts

Renamed (.mjs → .ts):

• lib/auth.ts (from auth.mjs)
• lib/codex.ts (from codex.mjs)
• lib/logger.ts (from logger.mjs)
• lib/request-transformer.ts (from request-transformer.mjs)
• lib/response-handler.ts (from response-handler.mjs)
• lib/server.ts (from server.mjs)

Documentation:

• README.md - Major updates with new configuration instructions

Deleted Files

• index.mjs - Replaced by index.ts
• test-config.json - Replaced by proper config examples
• test-config.mjs - No longer needed

🔍 Key Implementation Details

Configuration Lookup

The plugin now properly looks up configuration by model name:

const modelConfig = getModelConfig(normalizedModel, userConfig);

Model names like "GPT 5 Codex Low (ChatGPT Subscription)" are used for UI selection, and the id field determines which base model is used (gpt-5-codex or gpt-5).

OAuth Success Flow

When users complete OAuth:

1. Server reads oauth-success.html at startup
2. On successful callback, serves animated page instead of plain HTML
3. User sees beautiful animated success message
4. Page shows terminal-style authentication flow with matrix effects

Build Process

npm run build  # Compiles TypeScript + copies HTML to dist/

The build process:

1. Compiles TypeScript to dist/
2. Copies oauth-success.html to dist/lib/
3. Excludes test files from distribution
4. Generates type declarations and source maps

Testing Strategy

npm test           # Run all 93 tests
npm test -- --ui   # Visual UI mode

Tests cover:

• OAuth flow and token management
• Platform detection and browser opening
• Configuration parsing and merging
• Request transformation logic
• Response handling (SSE to JSON)
• All helper functions

📈 Impact

For Users

• Better Experience: 9 reasoning variants matching Codex CLI
• Beautiful OAuth: Professional animated success page
• Clear Setup: Comprehensive docs and ready-to-use configs
• Flexibility: From minimal to full configuration options

For Developers

• Maintainability: Modular code with clear separation of concerns
• Type Safety: Strict TypeScript prevents runtime errors
• Testability: 93 tests ensure reliability
• Documentation: Comprehensive guides for both AI and human maintainers

For the Plugin

• Quality: Strict typing and comprehensive testing
• Reliability: All critical paths tested
• Maintainability: AI-optimized architecture with AGENTS.md guide
• Future-Ready: Easy to extend with new features

🧪 Testing Performed

• ✅ All 93 tests pass
• ✅ TypeScript compilation successful
• ✅ Type checking passes (strict mode)
• ✅ Build process works correctly
• ✅ HTML asset properly bundled
• ✅ Test files excluded from dist

🚀 Migration Guide

For Existing Users

Option 1: Full Configuration (Recommended)
Copy config/full-opencode.json to your opencode config for all 9 model variants.

Option 2: Minimal Configuration
Continue with minimal config - plugin defaults unchanged (medium/auto/medium).

Build Requirement
If using local development, rebuild after pulling:

npm run build

📸 Screenshots

OAuth Success Page

• Matrix rain background with interactive mouse effects
• Animated terminal window with glowing borders
• Checkmark animation with spinning rings
• Professional OpenCode branding

Configuration Structure

{
  "provider": {
    "openai": {
      "options": { /* defaults */ },
      "models": {
        "GPT 5 Codex Low (ChatGPT Subscription)": {
          "id": "gpt-5-codex",
          "options": { "reasoningEffort": "low" }
        }
        // ... 8 more variants
      }
    }
  }
}

🎯 Next Steps

After merging:

1. Publish new version to npm (suggest v2.0.0 for major rewrite)
2. Update releases page with migration notes
3. Consider creating demo video of OAuth success page
4. Gather user feedback on model variant naming

📝 Notes

• Breaking Changes: Plugin now uses TypeScript (requires build step for local dev)
• Backward Compatible: Configuration structure enhanced but old configs still work
• No New Dependencies: Still only uses @openauthjs/openauth for runtime
• Test Infrastructure: New devDependencies for TypeScript and Vitest

---

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]