headquarter/docs/api/repositories.md

# Repositories API

Git repository and file management endpoints.

## Authentication

All endpoints require authentication (session cookie).

---

## GET /repositories

**Description:** List all repositories owned by the user, including external repositories not tied to any project.

### Response

#### Success (200 OK)

```json
[
  {
    "id": "uuid",
    "name": "my-external-repo",
    "remote_url": "https://github.com/user/repo.git",
    "is_mirror": false,
    "project_id": null,
    "owner_id": "uuid",
    "created_at": "2024-01-01T00:00:00Z"
  }
]
```

---

## POST /repositories

**Description:** Create a new external repository (not tied to any project). External repositories can be used across all projects for config profile git mounts.

### Request

#### Request Body

```json
{
  "name": "my-external-repo",
  "remote_url": "https://github.com/user/repo.git",
  "ssh_key_id": "uuid"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Repository name (unique per user for external repos) |
| `remote_url` | `string` | No | Remote URL to clone from |
| `ssh_key_id` | `string` | No | SSH key ID for authentication |
| `force_original_url` | `boolean` | No | Skip URL parsing (default: false) |

### Response

#### Success (201 Created)

```json
{
  "id": "uuid",
  "name": "my-external-repo",
  "path": "/data/repos/external/{user_id}/{repo_id}",
  "remote_url": "https://github.com/user/repo.git",
  "is_mirror": false,
  "project_id": null,
  "owner_id": "uuid",
  "ssh_key_id": "uuid",
  "created_at": "2024-01-01T00:00:00Z"
}
```

---

## GET /projects/{project_id}/repositories

**Description:** List repositories in a project.

### Response

#### Success (200 OK)

```json
[
  {
    "id": "uuid",
    "name": "my-repo",
    "clone_url": "https://github.com/user/repo.git",
    "is_mirror": true,
    "project_id": "uuid",
    "created_at": "2024-01-01T00:00:00Z"
  }
]
```

---

## POST /projects/{project_id}/repositories

**Description:** Create a new repository.

### Request

#### Request Body

```json
{
  "name": "my-repo",
  "remote_url": "https://github.com/user/repo.git",
  "is_mirror": false
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Repository name |
| `remote_url` | `string` | No | Remote URL to clone from |
| `is_mirror` | `boolean` | No | Create mirror clone (default: false) |

### Response

#### Success (201 Created)

```json
{
  "id": "uuid",
  "name": "my-repo",
  "clone_url": "https://github.com/user/repo.git",
  "is_mirror": false,
  "project_id": "uuid",
  "created_at": "2024-01-01T00:00:00Z"
}
```

#### URL Parsing Suggestion (422 Unprocessable Entity)

If the URL appears to be a browser URL:

```json
{
  "detail": "URL appears to be a browser URL, not a git clone URL",
  "suggested_url": "https://github.com/user/repo.git",
  "original_url": "https://github.com/user/repo/tree/main",
  "error_code": "URL_NEEDS_PARSING"
}
```

---

## DELETE /projects/{project_id}/repositories/{id}

**Description:** Delete a repository.

### Response

#### Success (204 No Content)

**Warning:** Permanently deletes the repository from disk. Cannot be undone.

---

## POST /projects/{project_id}/repositories/parse-url

**Description:** Parse and validate a git URL.

### Request

#### Request Body

```json
{
  "url": "https://github.com/user/repo/tree/main"
}
```

### Response

#### Success (200 OK)

```json
{
  "original_url": "https://github.com/user/repo/tree/main",
  "base_url": "https://github.com/user/repo.git",
  "is_valid_clone_url": false,
  "needs_parsing": true,
  "host": "github.com",
  "message": "This URL contains a branch path. The repository URL is: https://github.com/user/repo.git"
}
```

---

## GET /projects/{project_id}/repositories/{id}/files

**Description:** List files in a directory.

### Request

#### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `branch` | `string` | No | Branch name (default: repository default) |
| `path` | `string` | No | Directory path (default: root) |

### Response

#### Success (200 OK)

```json
{
  "path": "src",
  "branch": "main",
  "entries": [
    {
      "name": "components",
      "type": "directory",
      "path": "src/components"
    },
    {
      "name": "main.py",
      "type": "file",
      "path": "src/main.py",
      "size": 1234,
      "last_commit": {
        "hash": "abc123",
        "message": "Initial commit",
        "author": "John Doe",
        "date": "2024-01-01T00:00:00Z"
      }
    }
  ]
}
```

---

## GET /projects/{project_id}/repositories/{id}/files/content

**Description:** Get file content.

### Request

#### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `branch` | `string` | Yes | Branch name |
| `path` | `string` | Yes | File path |

### Response

#### Success (200 OK)

```json
{
  "path": "src/main.py",
  "branch": "main",
  "content": "function hello() {\n  return 'world';\n}",
  "size": 42,
  "encoding": "utf-8",
  "language": "python",
  "is_binary": false
}
```

#### Binary File (200 OK)

```json
{
  "path": "image.png",
  "branch": "main",
  "content": null,
  "size": 12345,
  "encoding": null,
  "language": null,
  "is_binary": true
}
```

---

## POST /projects/{project_id}/repositories/{id}/files/content

**Description:** Update file content and commit.

### Request

#### Request Body

```json
{
  "path": "src/main.py",
  "branch": "main",
  "content": "new content",
  "commit_message": "Update file",
  "author_name": "User",
  "author_email": "user@example.com"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | `string` | Yes | File path |
| `branch` | `string` | Yes | Branch name |
| `content` | `string` | Yes | New file content |
| `commit_message` | `string` | Yes | Commit message |
| `author_name` | `string` | Yes | Author name |
| `author_email` | `string` | Yes | Author email |

### Response

#### Success (200 OK)

```json
{
  "commit_hash": "def789",
  "message": "Update file",
  "branch": "main"
}
```

---

## GET /projects/{project_id}/repositories/{id}/branches

**Description:** List branches.

### Response

#### Success (200 OK)

```json
{
  "branches": [
    {
      "name": "main",
      "is_default": true,
      "last_commit": {
        "hash": "abc123",
        "message": "Initial commit",
        "date": "2024-01-01T00:00:00Z"
      }
    }
  ],
  "default_branch": "main"
}
```

---

## GET /projects/{project_id}/repositories/{id}/history

**Description:** Get commit history.

### Request

#### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `branch` | `string` | No | Branch name (default: all branches) |
| `max_count` | `integer` | No | Maximum commits to return (default: 1000) |

### Response

#### Success (200 OK)

```json
{
  "commits": [
    {
      "hash": "abc123",
      "author_name": "John Doe",
      "author_email": "john@example.com",
      "author_date": "2024-01-01T00:00:00Z",
      "message": "Initial commit",
      "refs": ["HEAD", "main"]
    }
  ],
  "branch": "main",
  "total_count": 50
}
```

---

## GET /projects/{project_id}/repositories/{id}/commits/{hash}

**Description:** Get commit details.

### Response

#### Success (200 OK)

```json
{
  "hash": "abc123",
  "author_name": "John Doe",
  "author_email": "john@example.com",
  "author_date": "2024-01-01T00:00:00Z",
  "committer_name": "John Doe",
  "committer_email": "john@example.com",
  "commit_date": "2024-01-01T00:00:00Z",
  "message": "Initial commit",
  "stats": {
    "files_changed": 2,
    "insertions": 10,
    "deletions": 0
  },
  "diff": "diff --git a/file.txt b/file.txt\n..."
}
```