Initial commit

2025-11-20 20:38:29 +01:00 · 2025-11-20 20:38:29 +01:00 · f2817bc1f1
commit f2817bc1f1
17 changed files with 2785 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,223 @@
+# 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.