cvs-proxy/ui/README.md

CVS Repository Browser UI

A modern, responsive web-based interface for browsing CVS repositories. Built with vanilla HTML, CSS, and JavaScript.

Features

• Repository Tree Navigation: Browse the complete repository structure with an intuitive file tree
• File Viewing: Display file contents with syntax highlighting support
• Revision History: View complete revision history for any file with author, date, and change information
• Diff Viewer: Compare different versions of files with color-coded diff output
• Real-time Status: Connection status indicator showing API health
• Responsive Design: Works on desktop and mobile devices

Architecture

File Structure

ui/
├── index.html      # Main HTML structure
├── styles.css      # Complete styling and responsive design
├── api.js          # API client for backend communication
├── ui.js           # UI management and DOM manipulation
├── app.js          # Main application logic and orchestration
└── README.md       # This file

Components

api.js - API Client

• Handles all communication with the backend /v1 endpoints
• Methods:
  • getTree(module) - Get repository structure
  • getFileContent(filePath, revision) - Get file contents
  • getFileHistory(filePath) - Get revision history
  • getDiff(filePath, rev1, rev2) - Get diff between revisions
  • getHealth() - Check API health

ui.js - UI Manager

• Manages DOM elements and view switching
• Handles tree rendering and navigation
• Displays file content, history, and diffs
• Provides utility functions for HTML escaping and formatting

app.js - Application Logic

• Orchestrates API calls and UI updates
• Manages application state
• Handles user interactions and event listeners
• Initializes the application on page load

styles.css - Styling

• Modern, clean design with CSS variables for theming
• Responsive layout that adapts to different screen sizes
• Color-coded diff display
• Smooth transitions and hover effects

Usage

Starting the Application

The UI is automatically served by the Flask application when you start the CVS Proxy:

python -m cvs_proxy.app

Then navigate to http://localhost:5000 in your browser.

Navigation

1. Browse Repository: The left sidebar shows the repository tree. Click on any file to view its contents.

2. View File: When a file is selected, its contents are displayed in the main area with action buttons.

3. View History: Click the "📋 History" button to see all revisions of the current file. Click on any revision to view that version.

4. Compare Versions: Click the "🔀 Diff" button to compare two revisions. Select the revisions from the dropdowns and click "Generate Diff".

5. Refresh: Click the refresh button (🔄) in the sidebar to reload the repository tree.

Styling

The UI uses CSS custom properties (variables) for easy theming:

--primary-color: #2563eb
--secondary-color: #6b7280
--success-color: #10b981
--danger-color: #ef4444
--bg-color: #f9fafb
--surface-color: #ffffff
--border-color: #e5e7eb
--text-primary: #111827
--text-secondary: #6b7280

Responsive Design

The UI is fully responsive and adapts to different screen sizes:

• Desktop: Sidebar on the left, main content on the right
• Tablet/Mobile: Sidebar collapses to a smaller height, content stacks vertically

Error Handling

The application includes comprehensive error handling:

• Connection errors are displayed in the status indicator
• API errors are shown in the main content area
• Loading states provide user feedback during operations
• Graceful fallbacks for missing data

Browser Compatibility

• Chrome/Chromium (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Development

Adding New Features

1. New API Endpoints: Add methods to the CVSProxyAPI class in api.js
2. UI Changes: Update the HTML in index.html and add styles to styles.css
3. Logic Changes: Modify the CVSRepositoryBrowser class in app.js
4. UI Utilities: Add helper methods to the UIManager class in ui.js

Debugging

Open the browser's Developer Console (F12) to see:

• API requests and responses
• JavaScript errors
• Application state logs

Performance Considerations

• File content is loaded on-demand
• Tree structure is built once and cached
• Diff generation is performed server-side
• Minimal DOM manipulation for smooth interactions

Security

• HTML content is properly escaped to prevent XSS attacks
• API calls use standard HTTP methods
• No sensitive data is stored in the browser
• CORS headers are handled by the Flask backend

Future Enhancements

• Search functionality for files
• Syntax highlighting for code files
• Blame view showing who changed each line
• Branch/tag support
• Download file functionality
• Keyboard shortcuts for navigation