Add README, config files and LICENSE

README.md

@@ -1,3 +1,287 @@
-# codexchange-cli
+# CodeXchange CLI
 
-A CLI tool that converts code between programming languages using local LLMs (Ollama), preserving logic, comments, and code style
+[![CI](https://img.shields.io/badge/Gitea-CI-blue)](https://7000pct.gitea.bloupla.net/7000pctAUTO/codexchange-cli/actions)
+[![Version](https://img.shields.io/badge/Version-0.1.0-green)](pyproject.toml)
+[![Python](https://img.shields.io/badge/Python-3.10+-blue)](https://www.python.org)
+[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
+
+A CLI tool that converts code between programming languages using local LLMs (Ollama), preserving logic, comments, and code style. Supports multi-language conversion with batch processing, syntax verification, and configurable model selection.
+
+## Features
+
+- **Multi-language Conversion**: Convert between JavaScript, TypeScript, Python, and Java
+- **Comment Preservation**: Maintains all comments, docstrings, and inline documentation
+- **Local LLM Integration**: Uses Ollama for privacy and cost-free conversions
+- **Configurable Models**: Choose from available Ollama models
+- **Batch Processing**: Convert entire directories recursively
+- **Syntax Verification**: Validate converted code syntax
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/codexchange-cli.git
+cd codexchange-cli
+pip install -e .
+```
+
+### Prerequisites
+
+- Python 3.10 or higher
+- [Ollama](https://ollama.ai/) installed and running locally
+- Required Ollama models (e.g., `codellama`, `llama2`)
+
+## Quick Start
+
+1. Make sure Ollama is running:
+   ```bash
+   ollama serve
+   ```
+
+2. Pull a code model:
+   ```bash
+   ollama pull codellama
+   ```
+
+3. Convert a single file:
+   ```bash
+   codexchange convert input.py --from python --to javascript -o output.js
+   ```
+
+4. List available models:
+   ```bash
+   codexchange list-models
+   ```
+
+5. List supported languages:
+   ```bash
+   codexchange list-languages
+   ```
+
+## Configuration
+
+CodeXchange uses a configuration file at `~/.codexchange.yaml`:
+
+```yaml
+ollama_host: http://localhost:11434
+default_model: codellama
+timeout: 300
+```
+
+### Environment Variables
+
+Override configuration with environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CODEXCHANGE_OLLAMA_HOST` | Ollama server URL | `http://localhost:11434` |
+| `CODEXCHANGE_DEFAULT_MODEL` | Default model name | `codellama` |
+| `CODEXCHANGE_TIMEOUT` | Request timeout (seconds) | `300` |
+
+## Usage
+
+### Convert a Single File
+
+```bash
+codexchange convert <input_file> --from <source_lang> --to <target_lang> [OPTIONS]
+```
+
+Options:
+- `-o, --output FILE`: Output file path
+- `-m, --model MODEL`: Ollama model to use
+- `-v, --verify`: Verify syntax after conversion
+
+Example:
+```bash
+codexchange convert script.py --from python --to typescript -o script.ts --model codellama
+```
+
+### Batch Conversion
+
+Convert all files in a directory:
+
+```bash
+codexchange batch-convert <directory> --from <source_lang> --to <target_lang> [OPTIONS]
+```
+
+Options:
+- `-o, --output DIRECTORY`: Output directory
+- `-m, --model MODEL`: Ollama model to use
+- `-r, --recursive`: Recursively process subdirectories (default: True)
+- `-c, --concurrency N`: Number of concurrent conversions (default: 1)
+- `-v, --verify`: Verify syntax after conversion
+
+Example:
+```bash
+codexchange batch-convert ./src --from python --to javascript --output ./dest -c 2
+```
+
+### List Available Models
+
+```bash
+codexchange list-models
+```
+
+### List Supported Languages
+
+```bash
+codexchange list-languages
+```
+
+## Supported Languages
+
+| Language | Extensions |
+|----------|------------|
+| JavaScript | .js, .jsx |
+| TypeScript | .ts, .tsx |
+| Python | .py |
+| Java | .java |
+
+### Supported Conversions
+
+- JavaScript <-> TypeScript
+- JavaScript <-> Python
+- JavaScript <-> Java
+- TypeScript <-> Python
+- TypeScript <-> Java
+- Python <-> Java
+
+## Examples
+
+### Convert Python to JavaScript
+
+```python
+# input.py
+def greet(name: str) -> str:
+    """Return a greeting message."""
+    return f"Hello, {name}!"
+```
+
+```javascript
+// output.js
+function greet(name) {
+    /** Return a greeting message. */
+    return `Hello, ${name}!`;
+}
+```
+
+### Convert TypeScript to Python
+
+```typescript
+// input.ts
+interface User {
+    id: number;
+    name: string;
+}
+
+function getUser(id: number): User {
+    return { id, name: "User" };
+}
+```
+
+```python
+# output.py
+class User:
+    def __init__(self, id: int, name: str):
+        self.id = id
+        self.name = name
+
+def get_user(id: int) -> User:
+    return User(id=id, name="User")
+```
+
+### Batch Convert with Syntax Verification
+
+```bash
+codexchange batch-convert ./python-src --from python --to javascript --output ./js-dest --verify -c 4
+```
+
+## Syntax Verification
+
+The `--verify` flag enables post-conversion syntax checking:
+
+- **Python**: Uses `ast.parse()` for validation
+- **TypeScript**: Uses `tsc --noEmit` (requires TypeScript)
+- **JavaScript**: Uses ESLint (requires Node.js)
+- **Java**: Basic brace/parentheses matching
+
+Warnings are displayed but don't block conversion completion.
+
+## Development
+
+### Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+### Type Checking
+
+```bash
+mypy src/codexchange/
+```
+
+### Linting
+
+```bash
+ruff check src/codexchange/ tests/
+```
+
+## Troubleshooting
+
+### Ollama connection failed
+
+**Error**: `Could not connect to Ollama at http://localhost:11434`
+
+**Solution**:
+1. Make sure Ollama is running: `ollama serve`
+2. Verify host URL in config: `~/.codexchange.yaml`
+3. Test connection: `codexchange list-models`
+
+### Model not found
+
+**Error**: `model not found`
+
+**Solution**:
+1. List available models: `codexchange list-models`
+2. Pull the model: `ollama pull <model-name>`
+3. Specify a different model: `codexchange convert ... --model <model>`
+
+### Invalid language pair
+
+**Error**: Conversion from X to Y is not supported
+
+**Solution**:
+1. Check supported languages: `codexchange list-languages`
+2. Verify both source and target languages are valid
+
+### Conversion timeout
+
+**Error**: Request timed out
+
+**Solution**:
+1. Increase timeout in config: `timeout: 600`
+2. Use a smaller model (e.g., `codellama` instead of `llama2`)
+3. Simplify the code being converted
+
+### Syntax verification failed
+
+**Error**: Syntax warnings after conversion
+
+**Solution**:
+1. Review the converted code for errors
+2. Try a different model
+3. Manually fix any issues
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `pytest tests/ -v`
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.