cvs-proxy/README.md

# CVS Proxy REST API

## Overview
CVS Proxy is a Flask-based REST API that provides a proxy for CVS (Concurrent Versions System) repository operations. It allows you to interact with CVS repositories through a RESTful interface, enabling programmatic access to repository information and file contents.

## Features
- List repository tree structure
- Compare file differences between revisions
- Retrieve file revision history
- Fetch raw file content at specific revisions
- Health check endpoint
- Docker containerization support

## Prerequisites
- Docker (recommended)
- OR
  - Python 3.8+
  - CVS command-line client installed
  - Virtual environment recommended

## Installation and Running

### Docker (Recommended)

1. Build the Docker image
```bash
docker build -t cvs-proxy .
```

2. Run the container with CVS repository URL
```bash
docker run -d \
  -p 5000:5000 \
  -e CVS_URL=:pserver:username@cvs.example.com:/path/to/repository \
  cvs-proxy
```

### Local Development

1. Clone the repository
```bash
git clone https://github.com/yourusername/cvs-proxy.git
cd cvs-proxy
```

2. Create and activate a virtual environment
```bash
python3 -m venv venv
source venv/bin/activate
```

3. Install dependencies using pip-compile
```bash
pip install -r requirements.txt
```

4. Install the package
```bash
pip install -e .
```

## Configuration

### Environment Variables

The following environment variables can be used to configure the CVS Proxy:

- `CVS_URL`: Full CVS repository URL (required)
  - Format: `:pserver:username@hostname:/path/to/repository`
- `FLASK_HOST`: Host to bind the server (default: 0.0.0.0)
- `FLASK_PORT`: Port to run the server (default: 5000)
- `FLASK_DEBUG`: Enable debug mode (default: false)

### Configuration Methods

1. Environment Variables (Recommended for Docker)
```bash
export CVS_URL=:pserver:username@cvs.example.com:/path/to/repository
```

2. .env File (For local development)
Create a `.env` file in the project root:
```
CVS_URL=:pserver:username@cvs.example.com:/path/to/repository
```

## API Endpoints

All endpoints are versioned with the `/v1` prefix.

### GET /v1/tree
List repository tree structure
- Optional query param: `module`

### GET /v1/diff
Get diff between two revisions of a file
- Required params: `file`, `rev1`, `rev2`

### GET /v1/history
Get revision history for a file
- Required param: `file`

### GET /v1/file
Get raw file content at a specific revision
- Required param: `file`
- Optional param: `revision`

### GET /v1/health
Simple health check endpoint

## Example Requests

1. List repository tree
```
GET /v1/tree
GET /v1/tree?module=project_name
```

2. Get file diff
```
GET /v1/diff?file=src/main.py&rev1=1.1&rev2=1.2
```

3. Get file history
```
GET /v1/history?file=README.md
```

4. Get file content
```
GET /v1/file?file=config.json
GET /v1/file?file=config.json&revision=1.3
```

## Web UI

The CVS Proxy includes a modern, responsive web-based interface for browsing repositories. The UI is automatically served from the root path (`/`) when the application starts.

### Features

- **Repository Tree Navigation**: Browse the complete repository structure
- **File Viewing**: Display file contents
- **Revision History**: View complete revision history for any file
- **Diff Viewer**: Compare different versions of files with color-coded output
- **Real-time Status**: Connection status indicator

### Accessing the UI

Once the application is running, open your browser and navigate to:
```
http://localhost:5000
```

For more details about the UI, see [ui/README.md](ui/README.md)

## Development

### Dependency Management

This project uses [pip-tools](https://github.com/jazzband/pip-tools) to manage dependencies with pinned versions for reproducible builds.

**Files:**
- `requirements.in`: Direct dependencies (source of truth)
- `requirements.txt`: Pinned dependencies (auto-generated by pip-compile)

**Updating Dependencies:**

1. To add a new dependency, edit `requirements.in` and add the package name
2. Regenerate `requirements.txt`:
```bash
pip-compile requirements.in
```

3. To update all dependencies to their latest versions:
```bash
pip-compile --upgrade requirements.in
```

4. Install the updated dependencies:
```bash
pip install -r requirements.txt
```

### Running Tests
```bash
python -m unittest discover cvs_proxy
```

## Project Structure

```
cvs-proxy/
├── cvs_proxy/
│   ├── __init__.py
│   ├── app.py              # Flask application with API endpoints
│   ├── cvs_client.py       # CVS client implementation
│   └── test_cvs_client.py  # Tests
├── ui/                     # Web-based repository browser
│   ├── index.html
│   ├── styles.css
│   ├── api.js
│   ├── ui.js
│   ├── app.js
│   └── README.md
├── openapi.yaml            # OpenAPI 3.0 specification
├── README.md               # This file
├── requirements.in         # Direct dependencies (source of truth)
├── requirements.txt        # Pinned dependencies (auto-generated)
├── setup.py
└── Dockerfile
```

## Security Considerations
- Ensure your CVS repository URL is correctly formatted
- Use secure, environment-specific configurations
- The API does not implement additional authentication beyond CVS repository configuration
- The UI properly escapes all HTML content to prevent XSS attacks

## License
[Specify your license here]

## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.