codexchange-cli/README.md

# CodeXchange CLI

[![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.