upsync 0.1.0

# upsync

[![Crates.io](https://img.shields.io/crates/v/upsync.svg)](https://crates.io/crates/upsync)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Cross-language project porting and synchronization tool powered by AI agents.

## Overview

`upsync` automates the process of porting projects between programming languages and keeping ports synchronized with upstream changes. It uses AI coding agents (Claude Code, Gemini CLI, or Codex CLI) to translate code while maintaining behavioral equivalence.

## Installation

```bash
cargo install upsync
```

Or build from source:

```bash
cargo install --path .
```

### Prerequisites

At least one AI coding agent must be installed:

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`)
- [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini`)
- [Codex CLI](https://github.com/openai/codex) (`codex`)

## Usage

### Port a New Project

Create a new port of an upstream project:

```bash
upsync port https://github.com/org/project --to rust
upsync port https://github.com/org/project --to go --output my-project
```

This will:
1. Clone the upstream repository
2. Detect the source language
3. Create a new project in the target language
4. Set up tracking for future synchronization

### Initialize an Existing Port

If you've already manually ported a project and want to track upstream changes:

```bash
cd your-ported-project
upsync init https://github.com/org/upstream-project
```

This will:
1. Clone the upstream repository to `.upstream-cache/`
2. Detect source and target languages
3. Create configuration files for sync tracking

### Check for Upstream Changes

```bash
upsync check
```

Fetches the latest upstream commits and reports how many lines have changed since the last sync.

### Sync with Upstream

```bash
upsync sync           # Apply changes
upsync sync --dry-run # Preview what would happen
```

The sync command:
1. Fetches upstream changes
2. Generates a diff since the last sync
3. Invokes the AI agent to apply equivalent changes
4. Runs verification to ensure the build passes
5. Updates the sync state

## Configuration

### upstream-sync.yml

Created in your project root:

```yaml
upstream: https://github.com/org/project
agent: claude          # Optional: claude, gemini, or codex (auto-detected if not set)
target_language: rust  # Optional: override detected language
verify_command: cargo check  # Optional: custom verification command
```

### .upstream-sync/state.json

Tracks synchronization state (managed automatically):

```json
{
  "last_synced_commit": "abc123...",
  "source_language": "typescript",
  "target_language": "rust"
}
```

### .upstream-cache/

Local clone of the upstream repository used for fetching changes.

## Supported Languages

| Language   | Extensions              | Default Verify Command |
|------------|-------------------------|------------------------|
| Rust       | `.rs`                   | `cargo check`          |
| Go         | `.go`                   | `go build ./...`       |
| TypeScript | `.ts`, `.tsx`           | `npm run build`        |
| JavaScript | `.js`, `.jsx`           | `npm run build`        |
| Python     | `.py`                   | `python -m py_compile` |
| Ruby       | `.rb`                   | -                      |
| Java       | `.java`                 | -                      |
| Kotlin     | `.kt`, `.kts`           | -                      |
| Swift      | `.swift`                | -                      |
| C          | `.c`, `.h`              | -                      |
| C++        | `.cpp`, `.hpp`, `.cc`   | -                      |
| C#         | `.cs`                   | -                      |

## How It Works

1. **Language Detection**: Counts file extensions to determine the dominant language
2. **Diff Generation**: Uses git to track changes between synced commits
3. **AI Translation**: Sends structured prompts to AI agents with:
   - Source and target language context
   - The upstream diff (for sync) or full codebase (for port)
   - Verification commands to run
4. **Retry Loop**: If verification fails, the agent is re-invoked with error context (up to 3 attempts)

## License

MIT