# Git Repository Management Specification

## Purpose

Manage git repositories as bare repos on disk with metadata in database.
## Requirements
### Requirement: Repository Creation

The system SHALL allow creating new bare git repositories with an optional SSH key association.

#### Scenario: Create repository
- GIVEN an authenticated user with a project
- WHEN they create a new repository
- THEN a bare repo is initialized on disk at `/data/repos/{user_id}/{project_id}/{repo_name}.git`
- AND metadata is stored in the database

#### Scenario: Create repository with SSH key
- **GIVEN** an authenticated user with a project
- **WHEN** they create a new repository with `ssh_key_id`
- **THEN** a bare repo is initialized on disk
- **AND** the SSH key association is stored in the database

### Requirement: Repository SSH key assignment
The system SHALL allow associating an SSH key with a GitRepository for clone operations and container git access.

#### Scenario: Assign SSH key at repository creation
- **GIVEN** an authenticated user creating a repository
- **WHEN** they provide an `ssh_key_id`
- **THEN** the repository is associated with that SSH key

#### Scenario: Update repository SSH key
- **GIVEN** an authenticated user with an existing repository
- **WHEN** they call `PATCH /repositories/{id}/ssh-key` with a new `ssh_key_id`
- **THEN** the repository's SSH key association is updated

### Requirement: Repository Cloning

The system SHALL support cloning external repositories.

#### Scenario: Clone repository
- GIVEN an authenticated user with a project
- WHEN they provide a remote URL
- THEN the system clones as a bare mirror
- AND stores it in the structured path

### Requirement: Repository Listing

The system SHALL list all user repositories.

#### Scenario: List repositories
- GIVEN an authenticated user
- WHEN they view the repositories page
- THEN all their repos are listed with name, path, and last push date

### Requirement: Repository Deletion
The system SHALL remove repository records when their owning project is deleted through authorized project deletion flow.

#### Scenario: Cascade repository cleanup
- GIVEN a project with associated repositories
- WHEN the project owner deletes the project
- THEN repository records for that project are removed
- AND repository listing no longer includes removed records

### Requirement: Duplicate Prevention

The system SHALL prevent duplicate repository names per project.

#### Scenario: Duplicate name
- GIVEN a project with a repo named "frontend"
- WHEN the user tries to create another "frontend" repo
- THEN the system rejects with a validation error

## Dependencies

- Database models: GitRepository, Project, User
- Docker volume for repo storage

## Quality Gates

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