codevf 1.0.0 → 1.0.2

package/ARCHITECTURE.md

@@ -1,285 +0,0 @@
-# Architecture Overview
-
-This document describes the internal architecture of the CodeVF CLI.
-
-## High-Level Design
-
-The CLI is designed as a **transport layer** between the customer and the CodeVF backend. It does not contain business logic - all intelligence lives in the backend.
-
-```
-┌──────────────┐
-│   Customer   │
-└──────┬───────┘
-       │
-       ├─ Commands (login, init, sync, fix)
-       │
-┌──────▼───────────────────────────────────────┐
-│          CodeVF CLI (Transport Layer)        │
-├──────────────────────────────────────────────┤
-│  • Authentication                            │
-│  • Configuration Management                  │
-│  • WebSocket Client                          │
-│  • Permission Manager                        │
-│  • Terminal UI (Ink/React)                   │
-└──────┬───────────────────────────────────────┘
-       │
-       │ HTTPS/WSS
-       │
-┌──────▼───────────────────────────────────────┐
-│         CodeVF Backend (Business Logic)      │
-├──────────────────────────────────────────────┤
-│  • Engineer Matching                         │
-│  • Task Management                           │
-│  • Billing                                   │
-│  • Code Analysis                             │
-│  • AI Tool Integration                       │
-└──────────────────────────────────────────────┘
-```
-
-## Module Structure
-
-### Commands Layer (`src/commands/`)
-Entry points for CLI commands. Thin wrappers that orchestrate modules.
-
-- **login.ts**: OAuth flow initiation and polling
-- **logout.ts**: Clear local authentication
-- **init.ts**: Project initialization wizard
-- **sync.ts**: Git sync workflow
-- **fix.tsx**: Live debugging session orchestration
-
-### Modules Layer (`src/modules/`)
-Core business logic and external integrations.
-
-#### AuthManager (`auth.ts`)
-- Manages authentication tokens
-- Stores in `~/.config/codevf/auth.json` with 0600 permissions
-- Token expiration checking
-- Auto-refresh (future)
-
-#### ConfigManager (`config.ts`)
-- Manages project configuration
-- Stores in `.codevf/config.json`
-- Tracks last sync metadata
-- Cache management
-
-#### ApiClient (`api.ts`)
-- HTTP client wrapper around axios
-- Automatic auth token injection
-- Error handling and retry logic
-- All backend API endpoints
-
-#### WebSocketClient (`websocket.ts`)
-- Real-time communication channel
-- Auto-reconnection with exponential backoff
-- Event-based message handling
-- Connection state management
-
-#### GitManager (`git.ts`)
-- Git operations wrapper
-- Branch management
-- Commit tracking
-- Status checking
-
-#### PermissionManager (`permissions.ts`)
-- Interactive permission prompts
-- Command approval
-- File access approval
-- Warning for sensitive files
-
-### UI Layer (`src/ui/`)
-Terminal-based user interfaces built with Ink (React for terminals).
-
-#### LiveSession (`LiveSession.tsx`)
-Real-time chat interface with:
-- Message history display
-- Input handling
-- Engineer info display
-- Billing display
-- Permission request overlays
-
-### Types Layer (`src/types/`)
-TypeScript type definitions for:
-- API contracts
-- WebSocket messages
-- Configuration schemas
-- Error types
-
-### Utils Layer (`src/utils/`)
-Utility functions:
-- **errors.ts**: Error handling and formatting
-- **detect.ts**: Project type detection
-- **upload.ts**: Repo archiving and upload
-
-## Data Flow
-
-### 1. Authentication Flow
-```
-Customer           CLI              Backend
-   │                │                   │
-   │─ codevf login ─▶│                   │
-   │                │─ POST /auth/init ─▶│
-   │                │◀─ {authUrl, poll} ─│
-   │◀─ Open browser ─│                   │
-   │                │                   │
-   │─ Authorize ─────────────────────────▶│
-   │                │                   │
-   │                │─ Poll /auth/token ─▶│
-   │                │◀─ {tokens} ────────│
-   │                │                   │
-   │◀─ Success ──────│                   │
-```
-
-### 2. Init Flow
-```
-Customer           CLI              Backend
-   │                │                   │
-   │─ codevf init ──▶│                   │
-   │                │─ Detect project ──│
-   │◀─ Wizard ───────│                   │
-   │─ Answers ───────▶│                   │
-   │                │─ POST /project/init▶│
-   │                │◀─ {projectId} ─────│
-   │                │─ Upload code ──────▶│
-   │                │─ Save config ──────│
-   │◀─ Summary ──────│                   │
-```
-
-### 3. Fix Session Flow
-```
-Customer           CLI              Backend         Engineer
-   │                │                   │               │
-   │─ codevf fix ───▶│                   │               │
-   │                │─ POST /tasks/create▶│               │
-   │                │◀─ {taskId} ────────│               │
-   │                │─ WS Connect ───────▶│               │
-   │                │                   │◀─ Accept task ─│
-   │                │◀─ engineer_connected◀───────────────│
-   │◀─ UI renders ──│                   │               │
-   │                │                   │               │
-   │◀─ Message ─────│◀─ engineer_message◀───────────────│
-   │─ Reply ────────▶│─ customer_message ──▶───────────▶│
-   │                │                   │               │
-   │                │◀─ request_command ◀───────────────│
-   │◀─ Approve? ────│                   │               │
-   │─ Yes ──────────▶│─ Run command ──────│               │
-   │                │─ command_output ────▶──────────────▶│
-   │                │                   │               │
-   │─ CTRL+C ───────▶│─ end_session ──────▶│               │
-   │◀─ Rate ────────│                   │               │
-   │─ Rating ───────▶│─ POST /tasks/rate ─▶│               │
-```
-
-## Security Model
-
-### Authentication
-- OAuth 2.0 with PKCE (backend handles)
-- JWT access tokens
-- Refresh tokens for long-lived sessions
-- Tokens stored with 0600 file permissions
-
-### Permission System
-- **Command Execution**: Explicit approval required
-- **File Access**: Per-file approval
-- **Git Access**: Restricted to `codevf` branch
-- **Code Upload**: Opt-in only
-
-### Network Security
-- All HTTP over TLS (HTTPS)
-- All WebSocket over TLS (WSS)
-- Certificate pinning (future)
-- Request signing for sensitive ops (future)
-
-## Error Handling
-
-### Error Hierarchy
-```
-CodeVFError (base)
-├── AuthError
-├── NetworkError
-├── ConfigError
-├── PermissionError
-└── GitError
-```
-
-### Error Recovery
-- **Network errors**: Auto-retry with backoff
-- **Auth errors**: Prompt to re-login
-- **Config errors**: Guide to initialization
-- **Git errors**: Provide git commands to fix
-
-## Extension Points
-
-### Future Enhancements
-1. **Plugin System**: Custom commands via plugins
-2. **Hooks**: Pre/post command hooks
-3. **Custom UI Themes**: Terminal color schemes
-4. **Local AI**: Optional local AI assistance
-5. **Multi-Project**: Manage multiple projects
-6. **Session Recording**: Record/replay sessions
-
-## Performance Considerations
-
-### Optimization Strategies
-- **Lazy Loading**: Load modules on-demand
-- **Streaming**: Stream large file uploads
-- **Compression**: Gzip HTTP responses
-- **Caching**: Cache project metadata
-- **Debouncing**: Debounce rapid WebSocket messages
-
-### Resource Limits
-- Max file size: 10MB per file
-- Max message size: 64KB
-- WebSocket timeout: 5 minutes idle
-- HTTP timeout: 30 seconds default, 2 minutes for uploads
-
-## Testing Strategy
-
-### Unit Tests
-- Pure functions in utils/
-- Module methods with mocked dependencies
-- React components with ink-testing-library
-
-### Integration Tests
-- Command flows with mocked API
-- WebSocket message handling
-- Git operations with test repo
-
-### E2E Tests (future)
-- Full command flows against staging backend
-- Real OAuth flow
-- Real WebSocket connections
-
-## Deployment
-
-### Build Process
-```bash
-npm run build    # TypeScript → JavaScript
-npm link         # Symlink for local testing
-npm publish      # Publish to NPM registry
-```
-
-### Distribution
-- **NPM Registry**: Primary distribution
-- **Homebrew**: macOS package manager
-- **apt/yum**: Linux package managers
-- **Scoop/Chocolatey**: Windows package managers
-
-### Versioning
-- Semantic Versioning (semver)
-- Breaking changes: Major version bump
-- New features: Minor version bump
-- Bug fixes: Patch version bump
-
-## Monitoring & Telemetry
-
-### Metrics (opt-in)
-- Command usage
-- Error rates
-- Session duration
-- Platform distribution
-
-### Privacy
-- No PII collected
-- No code sent without consent
-- Anonymized metrics only
-- Opt-out available

package/BUILD_SUMMARY.md

@@ -1,340 +0,0 @@
-# CodeVF CLI - Build Summary
-
-## Project Overview
-
-Successfully built a fully-functional CLI tool for CodeVF that enables customers to:
-- Authenticate with OAuth
-- Initialize projects
-- Upload code metadata
-- Start live debugging sessions with engineers
-- Safely interact with engineers in the terminal
-- Manage Git branches
-- Track credit usage
-
-## What Was Built
-
-### 1. Core Infrastructure ✅
-- **TypeScript Project**: Full TypeScript setup with ESM modules
-- **Package Configuration**: Modern Node.js package with all dependencies
-- **Build System**: TypeScript compilation to dist/
-- **CLI Framework**: yargs-based command routing
-
-### 2. Authentication System ✅
-- **AuthManager**: Token storage and management
-- **OAuth Flow**: Browser-based authentication
-- **Secure Storage**: ~/.config/codevf/auth.json with 0600 permissions
-- **Token Expiration**: Automatic expiration checking
-
-### 3. Project Management ✅
-- **ConfigManager**: .codevf/config.json management
-- **Project Detection**: Auto-detect Node, Python, Go, Ruby, Java, Rust
-- **Init Wizard**: Interactive project setup with prompts
-- **Code Upload**: Zip and upload project snapshot
-
-### 4. Git Integration ✅
-- **GitManager**: Wrapper around simple-git
-- **Branch Management**: Create and switch to codevf branch
-- **Sync Command**: Sync commits with backend
-- **Dirty State Detection**: Prevent sync with uncommitted changes
-
-### 5. Live Debugging Session ✅
-- **WebSocket Client**: Real-time bidirectional communication
-- **Live UI**: Ink/React-based terminal interface
-- **Chat Interface**: Engineer ↔ Customer messaging
-- **Permission System**: Approve commands and file access
-- **Billing Display**: Real-time credit tracking
-- **Session Management**: Start, run, end with rating
-
-### 6. API Client ✅
-- **HTTP Client**: axios-based wrapper
-- **All Endpoints**: login, init, sync, tasks, upload
-- **Error Handling**: Network, auth, and API errors
-- **Auto-retry**: Connection retry logic
-
-### 7. Security Features ✅
-- **Permission Requests**: Every command requires approval
-- **File Warnings**: Warn about sensitive files
-- **Secure Storage**: Proper file permissions
-- **Branch Isolation**: Engineers limited to codevf branch
-
-## File Structure
-
-```
-CodeVF-CLI/
-├── src/
-│   ├── commands/          # CLI command implementations
-│   │   ├── login.ts      # OAuth authentication
-│   │   ├── logout.ts     # Clear auth
-│   │   ├── init.ts       # Project initialization wizard
-│   │   ├── sync.ts       # Git sync
-│   │   └── fix.tsx       # Live debug session
-│   ├── modules/           # Core modules
-│   │   ├── auth.ts       # Auth token management
-│   │   ├── config.ts     # Config file management
-│   │   ├── api.ts        # HTTP API client
-│   │   ├── git.ts        # Git operations
-│   │   ├── websocket.ts  # WebSocket client
-│   │   └── permissions.ts # Permission manager
-│   ├── ui/                # Terminal UI
-│   │   └── LiveSession.tsx # Ink-based live session UI
-│   ├── types/
-│   │   └── index.ts      # TypeScript types
-│   ├── utils/
-│   │   ├── errors.ts     # Error handling
-│   │   ├── detect.ts     # Project detection
-│   │   └── upload.ts     # File upload utilities
-│   └── index.ts           # CLI entry point
-├── dist/                  # Compiled JavaScript
-├── claude.md              # Technical specification
-├── ARCHITECTURE.md        # Architecture documentation
-├── QUICKSTART.md          # Quick start guide
-├── CONTRIBUTING.md        # Contribution guide
-├── README.md              # User documentation
-├── package.json           # NPM package config
-├── tsconfig.json          # TypeScript config
-└── jest.config.js         # Test configuration
-```
-
-## Commands Implemented
-
-### ✅ `codevf login`
-- Opens browser for OAuth
-- Polls backend for token
-- Saves to ~/.config/codevf/auth.json
-- Validates and shows success
-
-### ✅ `codevf logout`
-- Clears auth.json
-- Shows confirmation
-
-### ✅ `codevf init`
-- Detects project type
-- Interactive wizard with prompts
-- Configures test/build commands
-- Allows AI tool selection
-- Optional code upload
-- Creates .codevf/config.json
-- Registers with backend
-
-### ✅ `codevf sync`
-- Checks git status
-- Validates branch
-- Gets commit hash
-- Syncs with backend
-- Saves last sync metadata
-- Shows summary
-
-### ✅ `codevf fix "<issue>"`
-- Creates task in backend
-- Connects WebSocket
-- Renders live UI with Ink
-- Handles chat messages
-- Manages permission requests
-- Executes approved commands
-- Uploads approved files
-- Displays screenshare links
-- Shows real-time billing
-- Handles CTRL+C gracefully
-- Collects engineer rating
-
-## Technology Stack
-
-### Dependencies Installed
-```json
-{
-  "yargs": "^17.7.2",          // CLI framework
-  "ink": "^4.4.1",             // Terminal UI
-  "react": "^18.2.0",          // UI components
-  "ws": "^8.16.0",             // WebSocket client
-  "axios": "^1.6.7",           // HTTP client
-  "ora": "^8.0.1",             // Loading spinners
-  "chalk": "^5.3.0",           // Terminal colors
-  "prompts": "^2.4.2",         // Interactive prompts
-  "archiver": "^6.0.1",        // Zip creation
-  "open": "^10.0.3",           // Browser opener
-  "simple-git": "^3.22.0",     // Git operations
-  "ignore": "^5.3.0",          // .gitignore parsing
-  "uuid": "^9.0.1",            // UUID generation
-  "date-fns": "^3.3.1"         // Date formatting
-}
-```
-
-### Dev Dependencies
-- TypeScript 5.3.3
-- tsx (development runner)
-- ESLint + TypeScript plugin
-- Prettier
-- Jest + ts-jest
-- @types/* for all packages
-
-## Build & Test
-
-### Build Successfully ✅
-```bash
-npm run build
-# Compiles TypeScript to dist/
-# Generates .d.ts type definitions
-# Creates source maps
-```
-
-### CLI Works ✅
-```bash
-node dist/index.js --help
-# Shows all commands
-
-node dist/index.js --version
-# Shows version 1.0.0
-```
-
-## Key Features Implemented
-
-### 🎯 Core Requirements Met
-- ✅ Works on macOS, Linux, Windows (Node.js cross-platform)
-- ✅ No root/admin required
-- ✅ HTTPS for all API calls
-- ✅ Secure local token storage
-- ✅ Simple transport layer (no business logic)
-
-### 🔒 Security
-- ✅ File permissions (0600 for auth.json)
-- ✅ Permission requests for all actions
-- ✅ Sensitive file warnings
-- ✅ Branch isolation (codevf branch)
-- ✅ Opt-in code upload
-
-### 🎨 User Experience
-- ✅ Interactive wizards
-- ✅ Auto-detection of project type
-- ✅ Beautiful terminal UI with Ink
-- ✅ Loading spinners and progress
-- ✅ Color-coded messages
-- ✅ Clear error messages
-- ✅ Helpful hints and next steps
-
-### 🔌 Backend Integration
-- ✅ All API endpoints implemented
-- ✅ WebSocket for real-time communication
-- ✅ Auto-reconnection logic
-- ✅ Error handling and retry
-- ✅ Token refresh preparation
-
-## What's Not Included (Non-Goals)
-
-As per specification:
-- ❌ PR creation from CLI (backend handles)
-- ❌ Local AI models
-- ❌ Code generation
-- ❌ Async task queues
-- ❌ Engineer assignment logic
-- ❌ GitHub/GitLab token management
-- ❌ Business logic (all in backend)
-
-## Testing Status
-
-### Ready for Testing
-- ✅ Build succeeds
-- ✅ CLI entry point works
-- ✅ All commands registered
-- ✅ Help system works
-- ✅ Version display works
-
-### Needs Backend
-The CLI is a complete transport layer but requires the backend API to be running for full functionality:
-- Authentication endpoints
-- Project management endpoints
-- Task creation and WebSocket
-- File upload endpoint
-
-### Test Checklist
-- [ ] Login flow with real OAuth
-- [ ] Init wizard with actual project
-- [ ] Code upload to real backend
-- [ ] Sync with real Git repo
-- [ ] Live session with WebSocket
-- [ ] Permission workflows
-- [ ] Error scenarios
-- [ ] Cross-platform testing (macOS, Linux, Windows)
-
-## Installation Methods
-
-### Development
-```bash
-npm install
-npm run build
-npm link
-codevf --help
-```
-
-### Production (when published)
-```bash
-npm install -g codevf-cli
-codevf --help
-```
-
-## Documentation Created
-
-1. **claude.md** - Complete technical specification
-2. **README.md** - User-facing documentation
-3. **QUICKSTART.md** - 5-minute quick start guide
-4. **ARCHITECTURE.md** - Internal architecture details
-5. **CONTRIBUTING.md** - Contribution guidelines
-6. **BUILD_SUMMARY.md** - This file
-
-## Next Steps
-
-### Before Production
-1. **Backend Development**: Implement all API endpoints
-2. **Integration Testing**: Test CLI against real backend
-3. **Error Scenarios**: Test all error paths
-4. **Cross-platform**: Test on Windows and Linux
-5. **Security Audit**: Review auth and permission flows
-6. **Performance**: Test with large repos
-7. **Documentation**: Add API examples
-
-### Future Enhancements
-1. **Unit Tests**: Add Jest tests for modules
-2. **E2E Tests**: Full workflow tests
-3. **CI/CD**: GitHub Actions for build and test
-4. **Plugin System**: Allow custom commands
-5. **Local Cache**: Cache engineer profiles
-6. **Session Recording**: Record/replay sessions
-7. **Multiple Projects**: Switch between projects
-8. **Offline Mode**: Basic commands without internet
-
-## Success Metrics
-
-### Technical ✅
-- ✅ Zero TypeScript errors
-- ✅ All dependencies installed
-- ✅ Builds successfully
-- ✅ CLI executable works
-- ✅ Modular architecture
-- ✅ Type-safe codebase
-
-### User Experience ✅
-- ✅ Clear command structure
-- ✅ Helpful error messages
-- ✅ Interactive wizards
-- ✅ Real-time UI
-- ✅ Permission prompts
-- ✅ Billing transparency
-
-### Security ✅
-- ✅ Secure token storage
-- ✅ Permission system
-- ✅ File warnings
-- ✅ Branch isolation
-- ✅ No credential leaks
-
-## Contact & Support
-
-- **Issues**: Create a GitHub issue
-- **Email**: support@codevf.com
-- **Docs**: https://docs.codevf.com
-
----
-
-**Built with**: TypeScript, Node.js, Ink, React, yargs
-**License**: MIT
-**Version**: 1.0.0
-**Status**: Ready for backend integration ✅