ccs/docs/project-roadmap.md

CCS Project Roadmap

Last Updated: 2025-12-19

Development roadmap documenting completed modularization phases and future work.

---

Completed Phases

Phase 1: Type System Modularization

Status: COMPLETE

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

---

Current Status

Metrics

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):

• model-pricing.ts (676 lines) - Data file
• glmt-proxy.ts (675 lines) - Complex proxy logic
• 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
• 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

Priority 1: Settings Page Split

Target: Split pages/settings.tsx (1,710 lines)

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

Priority 2: Analytics Page Split

Target: Split pages/analytics.tsx (420 lines)

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

Priority 3: Auth Monitor Split

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

---

Development Milestones

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

---

Success Criteria

Code Quality

• 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

---

Related Documentation

• Codebase Summary - Current structure
• Code Standards - Patterns and conventions
• System Architecture - Architecture diagrams
• CLAUDE.md - AI development guidance