ai(rules[claude]) Add CLAUDE.md for claude code

Author: tony

CLAUDE.md

@@ -0,0 +1,125 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+libvcs is a lite, typed Python tool for:
+- Detecting and parsing URLs for Git, Mercurial, and Subversion repositories
+- Providing command abstractions for git, hg, and svn
+- Synchronizing repositories locally
+- Creating pytest fixtures for testing with temporary repositories
+
+The library powers [vcspull](https://www.github.com/vcs-python/vcspull/).
+
+## Development Environment
+
+This project uses:
+- Python 3.9+ 
+- [uv](https://github.com/astral-sh/uv) for dependency management
+- [ruff](https://github.com/astral-sh/ruff) for linting and formatting
+- [mypy](https://github.com/python/mypy) for type checking
+- [pytest](https://docs.pytest.org/) for testing
+
+## Common Commands
+
+### Setting Up Environment
+
+```bash
+# Install dependencies
+uv pip install --editable .
+uv pip sync
+
+# Install with development dependencies
+uv pip install --editable . -G dev
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+# or directly with pytest
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/sync/test_git.py
+
+# Run a specific test
+uv run pytest tests/sync/test_git.py::test_remotes
+
+# Run tests with test watcher
+make start
+# or
+uv run ptw .
+```
+
+### Linting and Type Checking
+
+```bash
+# Run ruff for linting
+make ruff
+# or directly
+uv run ruff check .
+
+# Format code with ruff
+make ruff_format
+# or directly
+uv run ruff format .
+
+# Run mypy for type checking
+make mypy
+# or directly
+uv run mypy src tests
+```
+
+### Documentation
+
+```bash
+# Build documentation
+make build_docs
+
+# Start documentation server with auto-reload
+make start_docs
+
+# Update documentation CSS/JS
+make design_docs
+```
+
+## Code Architecture
+
+libvcs is organized into three main modules:
+
+1. **URL Detection and Parsing** (`libvcs.url`)
+   - Base URL classes in `url/base.py`
+   - VCS-specific implementations in `url/git.py`, `url/hg.py`, and `url/svn.py`
+   - URL registry in `url/registry.py`
+   - Constants in `url/constants.py`
+
+2. **Command Abstraction** (`libvcs.cmd`)
+   - Command classes for git, hg, and svn in `cmd/git.py`, `cmd/hg.py`, and `cmd/svn.py`
+   - Built on top of Python's subprocess module (via `_internal/subprocess.py`)
+
+3. **Repository Synchronization** (`libvcs.sync`)
+   - Base sync classes in `sync/base.py`
+   - VCS-specific sync implementations in `sync/git.py`, `sync/hg.py`, and `sync/svn.py`
+
+4. **Internal Utilities** (`libvcs._internal`)
+   - Subprocess wrappers in `_internal/subprocess.py`
+   - Data structures in `_internal/dataclasses.py` and `_internal/query_list.py`
+   - Runtime helpers in `_internal/run.py` and `_internal/shortcuts.py`
+
+5. **pytest Plugin** (`libvcs.pytest_plugin`)
+   - Provides fixtures for creating temporary repositories for testing
+
+## Testing Strategy
+
+libvcs uses pytest for testing with many custom fixtures. The pytest plugin (`pytest_plugin.py`) defines fixtures for creating temporary repositories for testing. These include:
+
+- `create_git_remote_repo`: Creates a git repository for testing
+- `create_hg_remote_repo`: Creates a Mercurial repository for testing
+- `create_svn_remote_repo`: Creates a Subversion repository for testing
+
+These fixtures handle setup and teardown automatically, creating isolated test environments.
+
+For running tests with actual VCS commands, tests will be skipped if the corresponding VCS binary is not installed.