Development

Development

Set up

git clone https://github.com/JCallico/imap-migration-tools.git
cd imap-migration-tools
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[tui]"
.venv/bin/python -m pip install -r requirements.txt

Read the repository's AGENTS.md before contributing.

Verify changes

Run from the repository root:

PYTHONPATH=src .venv/bin/python -m pytest test/ -v
.venv/bin/python -m ruff check src/ tools/ test/
.venv/bin/python -m ruff format --check src/ tools/ test/
git diff --check

Some integration tests bind loopback ports for local mock IMAP servers. Restricted environments must grant local socket permission rather than removing integration coverage.

Structure

Location	Responsibility
src/imap_*.py	Primary CLI entry points
src/*_imap_*.py	Legacy compatibility wrappers
src/cli/	Argument parsing and command configuration
src/auth/	OAuth2 and encrypted credential caching
src/core/	Shared IMAP and migration behavior
src/providers/	Provider-specific behavior
src/tui/	Terminal interface
src/utils/	Shared utilities
test/	Unit and local integration tests

Target Python 3.9 compatibility and follow Ruff's configuration. Preserve public CLI options, environment variables, entry points, and legacy wrapper behavior.