headquarter/openspec/specs/git-repo/spec.md

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.

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

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