chore: archive git-repo-management change

2026-05-18 15:48:27 +02:00
parent 4e2edb1d93
commit 9f7a750898
5 changed files with 170 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-18
@@ -0,0 +1,53 @@
+## Context
+
+The platform has projects and SSH keys but no git repository management. Users need to create bare repos for their projects and optionally clone external ones.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create bare git repositories on disk within project structure
+- List repositories per project
+- Clone external repositories as bare mirrors
+- Delete repositories (cascade with project deletion)
+- Prevent duplicate repo names per project
+
+**Non-Goals:**
+- Git hosting (push/pull via SSH/HTTP)
+- Webhook handling
+- CI/CD integration
+- Repository browsing/file viewing
+
+## Decisions
+
+1. **Bare repositories only**
+   - Simplifies storage, no working tree needed
+   - Standard pattern for git servers
+
+2. **Storage path: `/data/repos/{user_id}/{project_id}/{name}.git`**
+   - Isolates repos by user and project
+   - Predictable structure
+
+3. **Use subprocess to run `git init --bare` and `git clone --mirror`**
+   - Standard git commands, no additional dependencies
+   - More reliable than git libraries for basic operations
+
+4. **Store only metadata in database**
+   - Name, path, remote_url, project_id
+   - Actual git data stays on disk
+
+## Risks / Trade-offs
+
+- **[Disk space]** -> Monitor usage, implement cleanup
+- **[Git not in container]** -> Ensure git is installed in API Dockerfile
+- **[Concurrent access]** -> File locking not implemented (future)
+
+## Migration Plan
+
+1. Create API endpoints
+2. Add git to Dockerfile
+3. Create frontend
+4. Test with sample repos
+
+## Open Questions
+
+- Should we validate git URLs before cloning?
@@ -0,0 +1,25 @@
+## Why
+
+Projects exist but users cannot create or manage git repositories. The platform needs to allow users to create bare repositories, clone external ones, and manage them within projects.
+
+## What Changes
+
+- Add backend API for git repository CRUD operations
+- Implement bare repository initialization on disk
+- Support cloning external repositories as mirrors
+- Add frontend page for repository management
+- Integrate with existing project structure
+
+## Capabilities
+
+### New Capabilities
+- `git-repo-management`: Full git repository lifecycle within projects
+
+### Modified Capabilities
+- `project-management`: Include repositories in project responses
+
+## Impact
+
+- New API endpoints under `/projects/{id}/repositories`
+- Disk storage at `/data/repos/{user_id}/{project_id}/{repo_name}.git`
+- Frontend repository list and creation UI
@@ -0,0 +1,62 @@
+## ADDED Requirements
+
+### Requirement: Repository Creation
+
+The system SHALL allow creating new bare git repositories within projects.
+
+#### Scenario: Create repository
+- GIVEN an authenticated user with a project
+- WHEN they POST a repository name
+- 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
+- AND the response includes the repository details
+
+#### Scenario: Duplicate name prevention
+- GIVEN a project with a repo named "frontend"
+- WHEN the user tries to create another "frontend" repo
+- THEN the system responds with 400 Bad Request
+
+### Requirement: Repository Cloning
+
+The system SHALL support cloning external repositories as bare mirrors.
+
+#### Scenario: Clone repository
+- GIVEN an authenticated user with a project
+- WHEN they provide a valid remote URL
+- THEN the system clones as a bare mirror
+- AND stores it in the structured path
+- AND records the remote URL in metadata
+
+#### Scenario: Invalid URL
+- GIVEN an authenticated user
+- WHEN they provide an invalid or unreachable URL
+- THEN the system responds with 400 Bad Request
+
+### Requirement: Repository Listing
+
+The system SHALL list all repositories for a project.
+
+#### Scenario: List repositories
+- GIVEN an authenticated user with a project
+- WHEN they GET the repositories endpoint
+- THEN all repos for that project are listed with name, path, and last push date
+
+### Requirement: Repository Deletion
+
+The system SHALL remove repository records and disk contents.
+
+#### Scenario: Delete repository
+- GIVEN a project owner
+- WHEN they delete a repository
+- THEN the database record is removed
+- AND the directory on disk is removed
+
+### Requirement: Project Cascade Delete
+
+The system SHALL clean up repositories when a project is deleted.
+
+#### Scenario: Cascade repository cleanup
+- GIVEN a project with associated repositories
+- WHEN the project owner deletes the project
+- THEN all repository records for that project are removed
+- AND all repository directories on disk are removed
@@ -0,0 +1,28 @@
+## 1. Backend Git Repository API
+
+- [x] 1.1 Create `apps/api/src/api/git_repositories.py` with endpoints for list, create, clone, and delete repositories.
+- [x] 1.2 Add Pydantic schemas for GitRepositoryCreate, GitRepositoryResponse.
+- [x] 1.3 Implement bare repository initialization using `git init --bare`.
+- [x] 1.4 Implement mirror cloning using `git clone --mirror`.
+- [x] 1.5 Add ownership validation (only project owner can manage repos).
+- [x] 1.6 Add duplicate name validation per project.
+- [x] 1.7 Register router in `apps/api/src/main.py`.
+- [x] 1.8 Add backend tests for repository CRUD operations.
+
+## 2. Frontend Git Repositories Page
+
+- [x] 2.1 Create `apps/web/src/api/git_repositories.ts` with API methods.
+- [x] 2.2 Create `apps/web/src/pages/git-repositories.tsx` with repo list, create form, and delete action.
+- [x] 2.3 Add route in `apps/web/src/router.tsx`.
+- [x] 2.4 Update project page to show associated repositories.
+
+## 3. Project Integration
+
+- [x] 3.1 Update project deletion to cascade delete repositories.
+- [x] 3.2 Update project response to include repository count.
+
+## 4. Verification
+
+- [x] 4.1 Run backend checks (pytest, ruff, mypy).
+- [x] 4.2 Run frontend checks (npm test, typecheck, lint, build).
+- [x] 4.3 Verify docker-compose config is valid.