ai-migrate-tools 0.1.4a1

LLM-powered code migrations at scale

AI Migration Tool

This tool runs code migrations at scale. It is designed to be run in two phases:

Setup:

• Initialize a new project
• Add example pairs showing migration patterns
• Generate a system prompt for the migration task
• Create a verification script

Migration:

• Run the migration script: ai-migrate migrate --project my-new-project
• Check the status of the migration
• Check out a branch for manual fixes
• Merge all successful migrations

Prerequisites

• Hermit installed

Installation

1. Clone this repository:

gh repo clone block/ai-migrate
cd ai-migrate

2. Set up the development environment using Hermit:

hermit init
uv sync

This will:

• Initialize the Hermit environment with Python and required tools
• Install all necessary Python packages

3. Create your project:

# Basic project initialization
uv run ai-migrate init

# Or initialize from a PR (recommended)
uv run ai-migrate init <project_dir> --pr=<pr_number> --description="Brief description of migration"

4. Fill in the blanks. The above command generated some files you should edit:
   • <project dir>/system_prompt.md: Modify this to suit your migration details.
   • examples/: Add pairs of example files showing migration patterns. Use uv run ai-migrate migrate --manage examples to manage examples, including generating from git history or from a PR.

Setting Up Examples

Add example pairs to your project's examples/ directory.

Example structure:

project/
├── examples/
│   ├── Example1.old.java
│   ├── Example1.new.java
│   ├── Example2.old.java
│   └── Example2.new.java

Usage

# Interactive CLI
uv run ai-migrate migrate

The interactive CLI provides a guided experience with:

• Interactive prompts for file paths and options
• Rich terminal output with colors and formatting
• Progress indicators during long-running operations
• Dialog-based selection for various options

Key Commands

# Initialize a new project
uv run ai-migrate init

# Migrate files
uv run ai-migrate migrate [FILE_PATHS]

# Check migration status
uv run ai-migrate status

# Check out a branch for manual fixes
uv run ai-migrate checkout FILE_PATH

# Merge all successful migrations
uv run ai-migrate merge-branches

# Get help for a specific command
uv run ai-migrate migrate --help

Project Selection

The interactive CLI now provides an easy way to select which migration project to use:

1. Automatic Project Selection: When you run a command without specifying a project directory, the CLI will:

   • First check the AI_MIGRATE_PROJECT_DIR environment variable
   • Then look for a .ai-migrate file in the current directory
   • If neither is found, show a selection dialog with available projects

2. Project Selection Dialog:

   • Shows all projects in the projects/ directory
   • Allows you to select the appropriate project for your migration task
   • Remembers your selection for the current command

3. Manual Project Specification:

   • Use --project-dir option to specify a project directly, or use --project to specify a pre-configured project
   • Set the AI_MIGRATE_PROJECT_DIR environment variable for persistent selection
   • Create a .ai-migrate file in your repository for project-specific settings

This makes it easy to work with multiple migration projects without having to remember and type their paths each time.

This will look as input for the specified file and load it if it exists as that or in the form of a .old. file. The script will write the output to the same file and move the previous version to a .old. file if not .old. previously existed. This way you can keep trying migrations having to move files around.

Command Comparison: Main Branch vs New CLI

Here's how commands from the main branch map to the new interactive CLI:

Main Branch Command	New Interactive CLI Command	Description
uv run ai-migrate projects init <path>	uv run ai-migrate init	Initialize a new project
uv run ai-migrate examples setup <ref>	uv run ai-migrate migrate --manage examples then select "setup"	Set up examples from git history
uv run ai-migrate examples add <file>	uv run ai-migrate migrate --manage examples then select "add"	Add a file as an example
uv run ai-migrate --files <file>	uv run ai-migrate migrate <file>	Migrate a specific file
uv run ai-migrate projects status	uv run ai-migrate status	Show migration status
uv run ai-migrate projects run --manifest-file=<file>	uv run ai-migrate migrate --manifest-file=<file>	Run migration using a manifest file
uv run ai-migrate projects run --rerun-passed	uv run ai-migrate migrate --rerun-passed	Re-run migrations that have already passed
uv run ai-migrate projects run --max-workers=<num>	uv run ai-migrate migrate --max-workers=<num>	Set maximum number of parallel workers
uv run ai-migrate projects run --local-worktrees	uv run ai-migrate migrate --local-worktrees	Create worktrees alongside the git repo
uv run ai-migrate projects checkout <file>	uv run ai-migrate checkout <file>	Check out the branch for a failed migration
uv run ai-migrate projects merge-branches	uv run ai-migrate merge-branches	Merge changes from migrator branches

New Features in Interactive CLI

The new CLI adds these capabilities not present in the main branch:

1. PR-Based Initialization:

   uv run ai-migrate init
   # Then follow interactive prompts for PR-based setup
   

2. Example Management UI:

   uv run ai-migrate migrate --manage examples
   # Interactive dialog for listing, adding, or generating examples
   

3. System Prompt Management:

   uv run ai-migrate migrate --manage system-prompt
   # Interactive dialog for viewing, editing, or generating system prompts
   

4. Automatic Evaluation Generation:

   # Disable automatic evaluation generation
   uv run ai-migrate migrate --dont-create-evals <file_paths>
   
   # Manage evaluations
   uv run ai-migrate migrate --manage evals
   

5. Rich Help System:

   uv run ai-migrate --help
   uv run ai-migrate <command> --help
   

Development

The project uses Hermit to manage Python versions and development tools. Available tools:

• Python 3.12
• Black (code formatting)
• Ruff (linting)
• MyPy (type checking)
• Pytest (testing)

To activate the Hermit environment in your shell:

eval "$(./bin/hermit env)"

Documentation

Additional documentation is available in the docs/ directory:

• Evaluation Runner - Documentation for the evaluation runner system
• Automatic Evaluation Generation - Documentation for the automatic evaluation generation feature

AI-Powered Project Setup

The tool now supports AI-powered project setup using GitHub PRs:

1. PR-Based Project Initialization:

   # Using the interactive CLI
   uv run ai-migrate init
   # Then follow the prompts
   

   This will:

   • Generate a system prompt based on the PR description and changes
   • Extract example patterns from the PR changes

2. Generate Examples from PR:

   # Using the interactive CLI
   uv run ai-migrate migrate --manage examples
   # Then select "from-pr" and follow the prompts
   

   This will analyze the PR changes and extract representative examples of the migration pattern.

3. Manage System Prompt:

   # Using the interactive CLI
   uv run ai-migrate migrate --manage system-prompt
   # Then select an action (view, edit, or generate) and follow the prompts
   

   This allows you to view, edit, or generate a new system prompt for your migration project.

Interactive CLI

The new interactive CLI provides a more user-friendly experience with:

1. Rich Terminal UI:

   • Colorized output for better readability
   • Progress bars and spinners for long-running operations
   • Formatted panels and tables for displaying information

2. Interactive Prompts:

   • File path completion for easier navigation
   • Selection dialogs for choosing options
   • Yes/no confirmations for important decisions

3. Guided Workflows:

   • Step-by-step guidance through complex operations
   • Clear error messages and recovery options
   • Contextual help and suggestions

4. Available Commands:

   • init - Initialize a new migration project
   • migrate - Migrate one or more files or manage project resources
     • Use --manage examples to manage example files
     • Use --manage system-prompt to view or edit the system prompt
     • Use --manage evals to manage evaluation test cases
     • Use --manifest-file to specify a manifest file for batch processing
     • Use --rerun-passed to re-run migrations that have already passed
     • Use --max-workers to set the maximum number of parallel workers
     • Use --local-worktrees to create worktrees alongside the git repo
     • Use --dont-create-evals to disable automatic evaluation generation
   • status - Show the status of migration projects
     • See which files are passing, failing, or have not been processed
   • checkout - Check out the branch for a failed migration attempt
     • Allows you to manually fix a migration that failed
   • merge-branches - Merge changes from migrator branches
     • Consolidate all successful migrations

To use the interactive CLI, simply run:

uv run ai-migrate

For specific commands:

# Initialize a new project
uv run ai-migrate init

# Migrate files
uv run ai-migrate migrate [FILE_PATHS]

# Check migration status
uv run ai-migrate status

# Check out a branch for manual fixes
uv run ai-migrate checkout FILE_PATH

# Merge all successful migrations
uv run ai-migrate merge-branches

# Get help for a specific command
uv run ai-migrate migrate --help

Automatic Evaluation Generation

The tool now automatically creates evaluation test cases from successful migrations. This helps build a comprehensive test suite and ensures that future versions of the migration system continue to work correctly.

How It Works

1. When a migration succeeds (passes verification), the system:

   • Captures the original source files before migration
   • Creates a new directory in the evals directory with a timestamp-based name
   • Saves the original files in the source subdirectory
   • Creates a manifest file with the verification command and file information

2. These evaluations can then be used to:

   • Test future versions of the migration system
   • Ensure that regressions don't occur
   • Benchmark performance and accuracy

Usage

By default, evaluations are automatically created for every successful migration. You can:

# Disable automatic evaluation creation
uv run ai-migrate migrate --dont-create-evals <file_paths>

# Manage evaluations
uv run ai-migrate migrate --manage evals

The evaluation management interface allows you to:

• List existing evaluations with details like file count and creation date
• Generate evaluations from a GitHub Pull Request
• Generate evaluations from recent successful migrations