# Repository Clone Mode Specification

## Purpose

Support host-side repository cloning for tool instances, enabling isolated development environments with full git history and SSH key access for container git operations.

## Requirements

### Requirement: Host-side repository cloning
The system SHALL clone repositories on the host filesystem before container startup when clone mode is selected.

#### Scenario: Clone repository with branch selection
- **GIVEN** a repository with a remote URL and SSH key
- **WHEN** an instance is created in clone mode with branch="feature-x"
- **THEN** the system runs `git clone --branch feature-x <remote_url> <instance_dir>/repo-clone/`
- **AND** the clone includes full history

#### Scenario: Clone repository with default branch
- **GIVEN** a repository with a remote URL and SSH key
- **WHEN** an instance is created in clone mode without specifying a branch
- **THEN** the system defaults to branch="main"
- **AND** runs `git clone --branch main <remote_url> <instance_dir>/repo-clone/`

### Requirement: SSH key preparation for containers
The system SHALL decrypt and prepare SSH keys for container mounting.

#### Scenario: Prepare SSH key files
- **GIVEN** a repository with an associated SSH key
- **WHEN** a clone-mode instance is started
- **THEN** the private key is decrypted and written to `instance_dir/.ssh/id_ed25519` with mode 600
- **AND** the public key is written to `instance_dir/.ssh/id_ed25519.pub`
- **AND** an SSH config is written to `instance_dir/.ssh/config` with `StrictHostKeyChecking no`

### Requirement: Repository dirty state detection
The system SHALL detect uncommitted changes in cloned repositories.

#### Scenario: Detect clean repository
- **GIVEN** a cloned repository with no changes
- **WHEN** dirty state is checked
- **THEN** the result indicates no uncommitted changes

#### Scenario: Detect dirty repository
- **GIVEN** a cloned repository with modified files
- **WHEN** dirty state is checked
- **THEN** the result indicates uncommitted changes with file details

## Dependencies

- Database models: GitRepository, ToolInstance, SSHKey
- Docker Compose volume mounting
- Git installed on host and in containers

## Quality Gates

- `pytest` must pass
- `mypy .` must pass
- `ruff check .` must pass
- `npm run typecheck` must pass
- `npm run lint` must pass