From 8b1c2fa4e9b12ef66a94a10dd5241cee6df3205f Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Fri, 30 Jan 2026 18:56:54 +0000 Subject: [PATCH] Add README, config files and LICENSE --- README.md | 288 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 286 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 78cb5d6..e57b2a1 100644 --- a/README.md +++ b/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 \ No newline at end of file +[![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 --from --to [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 --from --to [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 ` +3. Specify a different model: `codexchange convert ... --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.