mirror of
https://github.com/tiennm99/ccs.git
synced 2026-10-15 02:16:27 +00:00
docs: update documentation for modularization phases 6-9
- mark settings, analytics, auth-monitor splits as complete - add test infrastructure (99 tests, 90% threshold) to roadmap - update codebase-summary.md with new modular structure - add github issues backlog (13 issues categorized by priority) - add future roadmap: multiple cliproxyapi, git worktree support - update project-overview-pdr.md with v7.0 release items - update system-architecture.md with new ui module structure
This commit is contained in:
kaitranntt committed
1 parent
c3f72e6693
commit
e45b46d207
4 files changed
+284
-277
No files matched your search
+136
-229
@@ -1,273 +1,180 @@
|
||||
# CCS Project Roadmap
|
||||
|
||||
Last Updated: 2025-12-19
|
||||
Last Updated: 2025-12-21
|
||||
|
||||
Development roadmap documenting completed modularization phases and future work.
|
||||
Forward-looking roadmap documenting current priorities, GitHub issues, and future feature plans.
|
||||
|
||||
---
|
||||
|
||||
## Completed Phases
|
||||
## Completed Modularization Summary
|
||||
|
||||
### Phase 1: Type System Modularization
|
||||
All major modularization work is complete. The codebase evolved from monolithic files to a well-structured modular architecture.
|
||||
|
||||
**Status**: COMPLETE
|
||||
| Phase | Description | Key Result |
|
||||
|-------|-------------|------------|
|
||||
| 1 | Type System | `src/types/` with barrel exports |
|
||||
| 2 | CLI Commands | `src/commands/` (8 handlers extracted) |
|
||||
| 3 | CLIProxy | `src/cliproxy/` with auth/, binary/, services/ subdirs |
|
||||
| 4 | Utils/Errors | `src/utils/ui/`, `src/errors/`, `src/management/` |
|
||||
| 5 | UI Components | 5 monster files split into modular dirs (54+ modules) |
|
||||
| 6 | Settings Page | `pages/settings/` (1,781→20 files) |
|
||||
| 7 | Analytics Page | `pages/analytics/` (420→8 files) |
|
||||
| 8 | Auth Monitor | `monitoring/auth-monitor/` (465→8 files) |
|
||||
| 9 | Test Infrastructure | 99 UI tests + 497 CLI tests, 90% coverage |
|
||||
|
||||
Extracted TypeScript types into dedicated `types/` directory with barrel exports.
|
||||
|
||||
**Changes**:
|
||||
- Created `src/types/` directory structure
|
||||
- Extracted types from inline definitions into dedicated files:
|
||||
- `config.ts` - Config, Settings, EnvVars
|
||||
- `cli.ts` - ParsedArgs, ExitCode, ClaudeCliInfo
|
||||
- `delegation.ts` - Session, execution types
|
||||
- `glmt.ts` - Message transformation types
|
||||
- `utils.ts` - ErrorCode, LogLevel, Result
|
||||
- Created `index.ts` barrel export aggregating all types
|
||||
|
||||
**Impact**:
|
||||
- Centralized type definitions
|
||||
- Cleaner imports across codebase
|
||||
- Easier type maintenance
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: CLI Command Extraction
|
||||
|
||||
**Status**: COMPLETE
|
||||
|
||||
Extracted CLI command handlers from main `ccs.ts` into dedicated `commands/` directory.
|
||||
|
||||
**Changes**:
|
||||
- Created `src/commands/` directory
|
||||
- Extracted command handlers:
|
||||
- `doctor-command.ts` - Health diagnostics
|
||||
- `help-command.ts` - Help text generation
|
||||
- `install-command.ts` - Install/uninstall logic
|
||||
- `shell-completion-command.ts` - Shell completions
|
||||
- `sync-command.ts` - Symlink synchronization
|
||||
- `update-command.ts` - Self-update logic
|
||||
- `version-command.ts` - Version display
|
||||
- `cliproxy-command.ts` - CLIProxy subcommands (634 lines)
|
||||
|
||||
**Impact**:
|
||||
- Reduced `ccs.ts` from ~1200 lines to 596 lines
|
||||
- Isolated command logic for easier testing
|
||||
- Clear separation of concerns
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: CLIProxy Modularization
|
||||
|
||||
**Status**: COMPLETE
|
||||
|
||||
Heavily modularized the CLIProxy integration module with internal subdirectories.
|
||||
|
||||
**Changes**:
|
||||
- Created subdirectory structure:
|
||||
- `auth/` - OAuth handlers, token management
|
||||
- `binary/` - Binary download and management
|
||||
- `services/` - Service layer abstractions
|
||||
- Created comprehensive barrel export (`index.ts` - 137 lines)
|
||||
- Maintained backward compatibility for all exports
|
||||
|
||||
**Key Files**:
|
||||
| File | Lines | Purpose |
|
||||
|------|-------|---------|
|
||||
| cliproxy-executor.ts | 666 | Main execution logic |
|
||||
| config-generator.ts | 531 | Config file generation |
|
||||
| account-manager.ts | 509 | Account management |
|
||||
| auth-handler.ts | - | Authentication handling |
|
||||
| proxy-detector.ts | - | Running proxy detection |
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Utility and Error Modularization
|
||||
|
||||
**Status**: COMPLETE
|
||||
|
||||
Extracted utilities and error handling into focused modules.
|
||||
|
||||
**Changes**:
|
||||
- Created `src/utils/` subdirectories:
|
||||
- `ui/` - Terminal UI (boxes, colors, spinners)
|
||||
- `websearch/` - Search integrations
|
||||
- Created `src/errors/` directory:
|
||||
- `error-handler.ts` - Main error handling
|
||||
- `exit-codes.ts` - Exit code definitions
|
||||
- `cleanup.ts` - Cleanup logic
|
||||
- Created `src/management/` directory:
|
||||
- `checks/` - Diagnostic checks
|
||||
- `repair/` - Auto-repair logic
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: UI Components Modularization
|
||||
|
||||
**Status**: COMPLETE
|
||||
|
||||
Major UI refactoring splitting monster files into focused modules.
|
||||
|
||||
**Monster Files Split**:
|
||||
|
||||
| Original File | Lines | Split Into |
|
||||
|---------------|-------|------------|
|
||||
| account-flow-viz.tsx | 1,144 | 12 modules in `flow-viz/` |
|
||||
| provider-editor.tsx | 921 | 13 modules in `provider-editor/` |
|
||||
| copilot-config-form.tsx | 846 | 13 modules in `config-form/` |
|
||||
| error-logs.tsx | 617 | 6 modules in `error-logs/` |
|
||||
| profile-editor.tsx | 531 | 10 modules in `editor/` |
|
||||
|
||||
**Domain Directories Created**:
|
||||
- `components/account/` - Account management (3 components + flow-viz)
|
||||
- `components/analytics/` - Usage charts (3 components)
|
||||
- `components/cliproxy/` - CLIProxy config (10 components + subdirs)
|
||||
- `components/copilot/` - Copilot settings (2 components + config-form)
|
||||
- `components/health/` - Health gauges (2 components)
|
||||
- `components/layout/` - App structure (3 components)
|
||||
- `components/monitoring/` - Error logs (3 components + error-logs)
|
||||
- `components/profiles/` - Profile management (4 components + editor)
|
||||
- `components/setup/` - Setup wizard (2 components + wizard)
|
||||
- `components/shared/` - Reusable components (19 components)
|
||||
|
||||
**Barrel Exports Added**:
|
||||
- Main barrel: `components/index.ts`
|
||||
- Domain barrels: One `index.ts` per domain directory
|
||||
- Subdirectory barrels: For split component directories
|
||||
**Metrics Achieved**:
|
||||
- Files >500 lines: 12 → 5 (-58%)
|
||||
- UI files >200 lines: 28 → 8 (-71%)
|
||||
- Barrel exports: 5 → 39 (+680%)
|
||||
- Test coverage: 0% → 90%
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
### Metrics
|
||||
### Remaining Large Files (Acceptable)
|
||||
|
||||
| Metric | Before | After | Change |
|
||||
|--------|--------|-------|--------|
|
||||
| Files > 500 lines | 12 | 7 | -42% |
|
||||
| UI files > 200 lines | 28 | 14 | -50% |
|
||||
| Barrel exports (CLI) | 5 | 24 | +380% |
|
||||
| Barrel exports (UI) | 0 | 11 | New |
|
||||
| Domain directories | 4 | 15 | +275% |
|
||||
|
||||
### Remaining Large Files
|
||||
|
||||
**CLI (Acceptable)**:
|
||||
**CLI** (complex core logic):
|
||||
- `model-pricing.ts` (676 lines) - Data file
|
||||
- `glmt-proxy.ts` (675 lines) - Complex proxy logic
|
||||
- `glmt-proxy.ts` (675 lines) - Streaming proxy
|
||||
- `cliproxy-executor.ts` (666 lines) - Core execution
|
||||
- `ccs.ts` (596 lines) - Entry point
|
||||
|
||||
**UI (Need Attention)**:
|
||||
- `pages/settings.tsx` (1,710 lines) - **HIGH PRIORITY SPLIT**
|
||||
**UI** (external/shadcn):
|
||||
- `components/ui/sidebar.tsx` (674 lines) - shadcn component
|
||||
- `monitoring/auth-monitor.tsx` (465 lines) - Could split
|
||||
- `pages/analytics.tsx` (420 lines) - Could split
|
||||
|
||||
---
|
||||
|
||||
## Future Work
|
||||
## GitHub Issues Backlog
|
||||
|
||||
### Priority 1: Settings Page Split
|
||||
### Critical (Blocking Users)
|
||||
|
||||
**Target**: Split `pages/settings.tsx` (1,710 lines)
|
||||
| Issue | Title | Type |
|
||||
|-------|-------|------|
|
||||
| #158 | AGY not working - Missing API Key - Run /login | bug |
|
||||
| #155 | Invalid JSON payload error with Gemini/Antigravity | bug |
|
||||
| #124 | Incorrect model ID for Claude 3.5 Sonnet (Thinking) | bug |
|
||||
|
||||
**Proposed Structure**:
|
||||
```
|
||||
pages/settings/
|
||||
├── index.tsx # Main layout
|
||||
├── general-section.tsx # General settings
|
||||
├── appearance-section.tsx # Theme, colors
|
||||
├── providers-section.tsx # Provider config
|
||||
├── websearch-section.tsx # WebSearch config
|
||||
├── advanced-section.tsx # Advanced options
|
||||
├── hooks.ts # Shared hooks
|
||||
└── types.ts # Settings types
|
||||
```
|
||||
### High Priority (Features)
|
||||
|
||||
### Priority 2: Analytics Page Split
|
||||
| Issue | Title | Type | Status |
|
||||
|-------|-------|------|--------|
|
||||
| #142 | Configure with available CLIProxyAPI | enhancement | **IN PROGRESS** |
|
||||
| #157 | Support for Kiro auth from CLIProxyAPIPlus | enhancement | - |
|
||||
| #123 | Add More Models | enhancement | Ongoing |
|
||||
| #114 | OpenCode Zen Free model + Auto Rotation API Key | enhancement | - |
|
||||
|
||||
**Target**: Split `pages/analytics.tsx` (420 lines)
|
||||
### Medium Priority
|
||||
|
||||
**Proposed Structure**:
|
||||
```
|
||||
pages/analytics/
|
||||
├── index.tsx # Main layout
|
||||
├── usage-overview.tsx # Usage summary
|
||||
├── model-breakdown.tsx # Per-model stats
|
||||
├── cost-analysis.tsx # Cost tracking
|
||||
└── hooks.ts # Data hooks
|
||||
```
|
||||
| Issue | Title | Type |
|
||||
|-------|-------|------|
|
||||
| #137 | CCS Cannot Connect to IDE, but Native Claude Works | support |
|
||||
| #89 | Add Claude Code CLI flag passthrough for delegation | enhancement |
|
||||
|
||||
### Priority 3: Auth Monitor Split
|
||||
### Low Priority / Questions
|
||||
|
||||
**Target**: Split `monitoring/auth-monitor.tsx` (465 lines)
|
||||
|
||||
**Proposed Structure**:
|
||||
```
|
||||
monitoring/auth-monitor/
|
||||
├── index.tsx # Main component
|
||||
├── provider-status.tsx # Provider cards
|
||||
├── token-display.tsx # Token info
|
||||
├── refresh-controls.tsx # Refresh actions
|
||||
└── hooks.ts # Auth hooks
|
||||
```
|
||||
|
||||
### Priority 4: Test Coverage
|
||||
|
||||
**Target**: Add tests for modularized components
|
||||
|
||||
- Unit tests for extracted utilities
|
||||
- Component tests for split UI modules
|
||||
- Integration tests for barrel exports
|
||||
- Snapshot tests for UI components
|
||||
|
||||
### Priority 5: Documentation
|
||||
|
||||
**Target**: Keep documentation synchronized
|
||||
|
||||
- Update codebase-summary.md on structural changes
|
||||
- Document new patterns in code-standards.md
|
||||
- Keep architecture diagrams current
|
||||
- Add inline JSDoc comments
|
||||
| Issue | Title | Type |
|
||||
|-------|-------|------|
|
||||
| #156 | Configure API for Zed IDE | docs |
|
||||
| #140 | Do we support ampcode? | question |
|
||||
| #111 | Factory droid CLI support | enhancement |
|
||||
| #103 | /context command returns incorrect context | invalid |
|
||||
|
||||
---
|
||||
|
||||
## Development Milestones
|
||||
## Future Roadmap
|
||||
|
||||
| Milestone | Status | Target Date |
|
||||
|-----------|--------|-------------|
|
||||
| Phase 1: Types | COMPLETE | - |
|
||||
| Phase 2: Commands | COMPLETE | - |
|
||||
| Phase 3: CLIProxy | COMPLETE | - |
|
||||
| Phase 4: Utils/Errors | COMPLETE | - |
|
||||
| Phase 5: UI Components | COMPLETE | - |
|
||||
| Phase 6: Settings Split | PENDING | Q1 2026 |
|
||||
| Phase 7: Remaining Splits | PENDING | Q1 2026 |
|
||||
| Phase 8: Test Coverage | PENDING | Q2 2026 |
|
||||
### Priority 1: Multiple CLIProxyAPI Instances
|
||||
|
||||
Support connecting to multiple CLIProxyAPI servers simultaneously.
|
||||
|
||||
**Use Cases**:
|
||||
- Load balancing across multiple proxy servers
|
||||
- Failover when primary server unavailable
|
||||
- Geographic distribution for latency optimization
|
||||
- Separate proxies for different provider groups
|
||||
|
||||
**Proposed Config**:
|
||||
```yaml
|
||||
cliproxy:
|
||||
instances:
|
||||
primary:
|
||||
url: http://localhost:8000
|
||||
providers: [gemini, codex]
|
||||
weight: 80
|
||||
secondary:
|
||||
url: http://192.168.1.100:8000
|
||||
providers: [agy]
|
||||
weight: 20
|
||||
failover:
|
||||
url: http://backup.example.com:8000
|
||||
priority: 2 # Only if primary/secondary fail
|
||||
strategy: weighted-round-robin
|
||||
```
|
||||
|
||||
### Priority 2: Native Git Worktree Support
|
||||
|
||||
Opt-in automatic git worktree management for features/issues.
|
||||
|
||||
**Use Cases**:
|
||||
- Automatic worktree creation when starting issue
|
||||
- Isolation of feature development
|
||||
- Easy cleanup after merge
|
||||
- Integration with GitHub issues
|
||||
|
||||
**Proposed Settings**:
|
||||
```yaml
|
||||
worktrees:
|
||||
enabled: true
|
||||
base_path: ~/.ccs/worktrees
|
||||
auto_create: true
|
||||
auto_cleanup: true
|
||||
naming: "{issue-number}-{short-title}"
|
||||
```
|
||||
|
||||
### Priority 3: Enhanced Model Support
|
||||
|
||||
- **#123**: Expand model catalog with new releases
|
||||
- **#124**: Fix Claude 3.5 Sonnet (Thinking) model ID
|
||||
- **#114**: OpenCode Zen free model + API key rotation
|
||||
|
||||
### Priority 4: IDE Integration
|
||||
|
||||
- **#137**: Debug CCS-to-IDE connection issues
|
||||
- **#156**: Zed IDE configuration documentation
|
||||
- **#140**: Investigate ampcode compatibility
|
||||
- **#111**: Factory droid CLI support assessment
|
||||
|
||||
### Priority 5: Authentication Enhancements
|
||||
|
||||
- **#158**: Fix AGY OAuth flow
|
||||
- **#157**: Add Kiro auth support from CLIProxyAPIPlus
|
||||
|
||||
---
|
||||
|
||||
## Milestones
|
||||
|
||||
| Milestone | Status | Target |
|
||||
|-----------|--------|--------|
|
||||
| Modularization (Phases 1-9) | COMPLETE | - |
|
||||
| Critical Bug Fixes (#158, #155, #124) | PLANNED | Q1 2026 |
|
||||
| Multiple CLIProxyAPI Instances | PLANNED | Q1 2026 |
|
||||
| Git Worktree Support | PLANNED | Q1 2026 |
|
||||
| Enhanced Model Support | PLANNED | Q2 2026 |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Code Quality
|
||||
All criteria achieved:
|
||||
|
||||
- [ ] All files under 200 lines (except documented exceptions)
|
||||
- [ ] Every directory has barrel export
|
||||
- [ ] No circular dependencies
|
||||
- [ ] TypeScript strict mode passing
|
||||
|
||||
### Maintainability
|
||||
|
||||
- [ ] Clear domain boundaries
|
||||
- [ ] Consistent naming conventions
|
||||
- [ ] Comprehensive documentation
|
||||
- [ ] Easy navigation for new developers
|
||||
|
||||
### Developer Experience
|
||||
|
||||
- [ ] Fast build times
|
||||
- [ ] Efficient tree-shaking
|
||||
- [ ] Clear import paths
|
||||
- [ ] Minimal cognitive load
|
||||
- [x] Files under 200 lines (except documented exceptions)
|
||||
- [x] Every directory has barrel export
|
||||
- [x] No circular dependencies
|
||||
- [x] TypeScript strict mode passing
|
||||
- [x] 90%+ test coverage
|
||||
- [x] Clear domain boundaries
|
||||
- [x] Consistent naming conventions
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user