[P0] Backend: Expose Git branch and commit APIs

[frankbria]

Problem

Steps 8-10 of the user journey require users to see git operations, but GitWorkflowManager is only used internally with no REST API exposure.

Current State

• GitWorkflowManager exists at codeframe/git/workflow_manager.py
• Has create_feature_branch(), commit_task_changes(), merge_to_main()
• Database has git_branches table
• No API endpoints expose this functionality

Required Implementation

New Router: /api/projects/{id}/git/

POST /api/projects/{id}/git/branches          # Create feature branch
GET  /api/projects/{id}/git/branches          # List branches
GET  /api/projects/{id}/git/branches/{name}   # Get branch details
POST /api/projects/{id}/git/commit            # Commit changes
GET  /api/projects/{id}/git/commits           # List commits
GET  /api/projects/{id}/git/status            # Get working tree status

WebSocket Events to Add

• branch_created - When feature branch created
• commit_created - Already exists, verify it fires

Acceptance Criteria

• New git.py router created
• All endpoints require authentication
• WebSocket events broadcast on operations
• Integration tests for all endpoints

Dependencies

• None (uses existing GitWorkflowManager)

Blocks

• #TBD (Git Commit UI)
• #TBD (PR Creation API)

Committee Report Reference

This was identified as a critical gap by 11/11 expert agents in the UX/UI committee review. Step 8 of the user journey is invisible without this API.

Updated Dependencies

• Blocks: [P0] Frontend: Git commit and branch visualization UI #271, [P0] Backend: GitHub PR creation and management API #272, [P1] Backend: Add WebSocket events for Git and PR operations #279

[traycerai]

Plan

Observations

The codebase has a well-established GitWorkflowManager at file:codeframe/git/workflow_manager.py with methods for branch creation, commits, and merging. The database layer has GitRepository for tracking git operations in the git_branches table. The API follows a consistent pattern using FastAPI routers with authentication via get_current_user and authorization via db.user_has_project_access(). WebSocket broadcasting infrastructure exists in file:codeframe/ui/websocket_broadcasts.py with a broadcast_commit_created function already implemented. The router registration pattern in file:codeframe/ui/server.py is straightforward using app.include_router().

Approach

Create a new git router at file:codeframe/ui/routers/git.py that exposes the existing GitWorkflowManager functionality through REST endpoints. The router will follow the established pattern: project-scoped routes (/api/projects/{project_id}/git/*), authentication/authorization checks, and WebSocket event broadcasting. Add a broadcast_branch_created helper to file:codeframe/ui/websocket_broadcasts.py to complement the existing broadcast_commit_created. Implement comprehensive integration tests following the existing test patterns in file:tests/api/. This approach leverages existing infrastructure without introducing new dependencies or architectural changes. The implementation is designed to unblock dependent tickets #271 (Git Commit UI), #272 (PR Creation API), and #279 (Git Merge API).

Implementation Steps

1. Create Git Router Module

File: file:codeframe/ui/routers/git.py

Create a new router with the following endpoints:

• POST /api/projects/{project_id}/git/branches - Create feature branch

  • Extract issue_number and issue_title from request body
  • Get project from database and verify it exists
  • Check authorization with db.user_has_project_access(current_user.id, project_id)
  • Get workspace path from project
  • Initialize GitWorkflowManager(workspace_path, db)
  • Call workflow_manager.create_feature_branch(issue_number, issue_title)
  • Broadcast branch_created event via WebSocket
  • Return branch details: {branch_name, issue_number, created_at, status: "active"}

• GET /api/projects/{project_id}/git/branches - List branches

  • Verify project exists and check authorization
  • Query database using db.git_branches.get_branches_by_status("active") filtered by project's issues
  • Return list of branches with: {id, branch_name, issue_id, status, created_at, merged_at, merge_commit}

• GET /api/projects/{project_id}/git/branches/{branch_name} - Get branch details

  • Verify project exists and check authorization
  • Query database for branch by name
  • Verify branch belongs to an issue in this project
  • Return branch details with associated issue information

• POST /api/projects/{project_id}/git/commit - Commit changes

  • Extract task_id, files_modified, agent_id from request body
  • Verify project exists and check authorization
  • Get task from database and verify it belongs to project
  • Get workspace path and initialize GitWorkflowManager
  • Call workflow_manager.commit_task_changes(task, files_modified, agent_id)
  • Call broadcast_commit_created() with commit details
  • Return commit details: {commit_hash, commit_message, files_changed, timestamp}

• GET /api/projects/{project_id}/git/commits - List commits

  • Verify project exists and check authorization
  • Get workspace path and initialize GitWorkflowManager
  • Use workflow_manager.repo.iter_commits() from GitPython to get commit history
  • Support query parameters: branch (default: current), limit (default: 50, max: 100)
  • Return list of commits: {hash, short_hash, message, author, timestamp, files_changed}

• GET /api/projects/{project_id}/git/status - Get working tree status

  • Verify project exists and check authorization
  • Get workspace path and initialize GitWorkflowManager
  • Call workflow_manager.get_current_branch()
  • Use workflow_manager.repo.is_dirty() and workflow_manager.repo.untracked_files
  • Return status: {current_branch, is_dirty, modified_files, untracked_files, staged_files}

Dependencies and imports:

from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional
from pathlib import Path
from codeframe.persistence.database import Database
from codeframe.ui.dependencies import get_db
from codeframe.auth.dependencies import get_current_user
from codeframe.auth.models import User
from codeframe.git.workflow_manager import GitWorkflowManager
from codeframe.ui.shared import manager
from codeframe.ui.websocket_broadcasts import broadcast_branch_created, broadcast_commit_created
import git

Request/Response Models:

• BranchCreateRequest: issue_number: str, issue_title: str
• BranchResponse: id: int, branch_name: str, issue_id: int, status: str, created_at: str, merged_at: Optional[str], merge_commit: Optional[str]
• CommitRequest: task_id: int, files_modified: List[str], agent_id: str
• CommitResponse: commit_hash: str, commit_message: str, files_changed: int, timestamp: str
• GitStatusResponse: current_branch: str, is_dirty: bool, modified_files: List[str], untracked_files: List[str], staged_files: List[str]
• CommitListResponse: hash: str, short_hash: str, message: str, author: str, timestamp: str, files_changed: int

2. Add WebSocket Broadcast Helper

File: file:codeframe/ui/websocket_broadcasts.py

Add new function after the existing broadcast_commit_created function (around line 237):

async def broadcast_branch_created(
    manager,
    project_id: int,
    branch_name: str,
    issue_number: str,
    issue_id: Optional[int] = None,
) -> None:
    """
    Broadcast git branch creation to connected clients.
    
    Args:
        manager: ConnectionManager instance
        project_id: Project ID
        branch_name: Git branch name created
        issue_number: Issue number the branch is for
        issue_id: Optional issue ID
    """
    message = {
        "type": "branch_created",
        "project_id": project_id,
        "branch_name": branch_name,
        "issue_number": issue_number,
        "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
    }
    
    if issue_id is not None:
        message["issue_id"] = issue_id
    
    try:
        await manager.broadcast(message, project_id=project_id)
        logger.debug(f"Broadcast branch_created: {branch_name} for issue {issue_number}")
    except Exception as e:
        logger.error(f"Failed to broadcast branch creation: {e}")

This function follows the same pattern as broadcast_commit_created and integrates with the existing WebSocket infrastructure.

3. Register Router in Server

File: file:codeframe/ui/server.py

Add import at line 20 (with other router imports):

from codeframe.ui.routers import (
    agents,
    blockers,
    chat,
    checkpoints,
    context,
    discovery,
    git,  # Add this line
    lint,
    metrics,
    projects,
    quality_gates,
    review,
    session,
    tasks,
    websocket,
)

Add router registration at line 342 (after other routers, before auth_router):

app.include_router(git.router)

4. Create Integration Tests

File: file:tests/api/test_git_api.py

Create comprehensive integration tests covering:

Test Class: TestGitBranchesAPI

• test_create_branch_success - Create branch with valid issue
• test_create_branch_unauthorized - Verify 403 when user lacks project access
• test_create_branch_project_not_found - Verify 404 for non-existent project
• test_create_branch_duplicate - Verify error when branch already exists
• test_list_branches - List all branches for project
• test_list_branches_empty - List branches when none exist
• test_get_branch_details - Get specific branch by name
• test_get_branch_not_found - Verify 404 for non-existent branch
• test_create_branch_broadcasts_websocket - Verify branch_created event is broadcast

Test Class: TestGitCommitsAPI

• test_commit_changes_success - Commit with valid task and files
• test_commit_changes_unauthorized - Verify 403 when user lacks access
• test_commit_changes_no_files - Verify error when files_modified is empty
• test_commit_changes_broadcasts_websocket - Verify commit_created event is broadcast
• test_list_commits - List commits with default parameters
• test_list_commits_with_limit - List commits with custom limit
• test_list_commits_empty_repo - Handle empty repository gracefully

Test Class: TestGitStatusAPI

• test_get_status_clean - Get status when working tree is clean
• test_get_status_with_changes - Get status with modified files
• test_get_status_unauthorized - Verify 403 when user lacks access

Test utilities:

• Use api_client fixture from file:tests/api/conftest.py
• Create helper function to set up test project with git repository
• Create helper function to create test issues and tasks
• Use real git operations for integration tests (not mocked)
• Ensure test repositories are cleaned up after each test

Example test structure:

import pytest
from fastapi.testclient import TestClient

class TestGitBranchesAPI:
    def test_create_branch_success(self, api_client: TestClient, test_project, test_issue):
        # When: POST /api/projects/{id}/git/branches
        response = api_client.post(
            f"/api/projects/{test_project['id']}/git/branches",
            json={"issue_number": test_issue['issue_number'], "issue_title": test_issue['title']}
        )
        # Then: Assert 201, branch created
        assert response.status_code == 201
        assert response.json()["branch_name"].startswith("issue-")
        
    def test_list_branches(self, api_client: TestClient, test_project):
        # When: GET /api/projects/{id}/git/branches
        response = api_client.get(f"/api/projects/{test_project['id']}/git/branches")
        # Then: Assert 200, correct branch list returned
        assert response.status_code == 200
        assert isinstance(response.json(), list)

5. Update Dependencies Helper (Optional Enhancement)

File: file:codeframe/ui/dependencies.py

Consider adding a helper to get GitWorkflowManager instance:

def get_git_workflow_manager(
    project_id: int,
    db: Database = Depends(get_db),
) -> GitWorkflowManager:
    """Get GitWorkflowManager for a project.
    
    Args:
        project_id: Project ID
        db: Database instance
        
    Returns:
        GitWorkflowManager instance for the project
        
    Raises:
        HTTPException: If project not found or has no workspace
    """
    project = db.get_project(project_id)
    if not project:
        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
    
    workspace_path = project.get("workspace_path")
    if not workspace_path:
        raise HTTPException(status_code=400, detail="Project has no workspace")
    
    return GitWorkflowManager(Path(workspace_path), db)

This can simplify endpoint implementations by reducing boilerplate and ensuring consistent error handling.

Sequence Diagram

sequenceDiagram
    participant Client
    participant GitRouter
    participant Auth
    participant Database
    participant GitWorkflowManager
    participant GitRepo
    participant WebSocket

    Client->>GitRouter: POST /api/projects/1/git/branches
    GitRouter->>Auth: Verify JWT token
    Auth-->>GitRouter: User authenticated
    GitRouter->>Database: Check user_has_project_access()
    Database-->>GitRouter: Access granted
    GitRouter->>Database: Get project workspace_path
    Database-->>GitRouter: workspace_path
    GitRouter->>GitWorkflowManager: create_feature_branch(issue_number, title)
    GitWorkflowManager->>GitRepo: Create git branch
    GitRepo-->>GitWorkflowManager: Branch created
    GitWorkflowManager->>Database: create_git_branch(issue_id, branch_name)
    Database-->>GitWorkflowManager: Branch ID
    GitWorkflowManager-->>GitRouter: branch_name
    GitRouter->>WebSocket: broadcast_branch_created()
    WebSocket-->>Client: branch_created event
    GitRouter-->>Client: 201 Created {branch_name, status}

Loading

This sequence applies to all endpoints: authentication is verified first, authorization is checked second, then the git operation is performed, and finally WebSocket events are broadcast.

Error Handling

All endpoints must handle:

• 403 Forbidden: User lacks project access (via user_has_project_access)
• 404 Not Found: Project, issue, task, or branch not found
• 400 Bad Request: Invalid parameters (empty issue_number, no files to commit, etc.)
• 500 Internal Server Error: Git operations fail (merge conflicts, repository errors)

Use try-except blocks around GitWorkflowManager operations to catch git.GitCommandError and convert to appropriate HTTP exceptions. Log all errors with context for debugging.

WebSocket Event Verification

Ensure the following events are properly broadcast:

• branch_created: When POST /git/branches succeeds (new event)
• commit_created: When POST /git/commit succeeds (existing event, verify it fires correctly)

Test WebSocket events in integration tests by subscribing to project updates and verifying messages are received. Use the test broadcast infrastructure in file:codeframe/ui/server.py (line 300-318) for testing.

Blocking Dependencies

This implementation unblocks the following dependent tickets:

• [P0] Frontend: Git commit and branch visualization UI #271: Git Commit UI - Requires the commit endpoint and commit_created WebSocket event
• [P0] Backend: GitHub PR creation and management API #272: PR Creation API - Requires the branches endpoint to list available branches
• 279: Git Merge API - Requires the branches endpoint and branch status tracking

These endpoints provide the foundational REST API that the dependent features build upon.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-established `GitWorkflowManager` at `file:codeframe/git/workflow_manager.py` with methods for branch creation, commits, and merging. The database layer has `GitRepository` for tracking git operations in the `git_branches` table. The API follows a consistent pattern using FastAPI routers with authentication via `get_current_user` and authorization via `db.user_has_project_access()`. WebSocket broadcasting infrastructure exists in `file:codeframe/ui/websocket_broadcasts.py` with a `broadcast_commit_created` function already implemented. The router registration pattern in `file:codeframe/ui/server.py` is straightforward using `app.include_router()`.

## Approach

Create a new git router at `file:codeframe/ui/routers/git.py` that exposes the existing `GitWorkflowManager` functionality through REST endpoints. The router will follow the established pattern: project-scoped routes (`/api/projects/{project_id}/git/*`), authentication/authorization checks, and WebSocket event broadcasting. Add a `broadcast_branch_created` helper to `file:codeframe/ui/websocket_broadcasts.py` to complement the existing `broadcast_commit_created`. Implement comprehensive integration tests following the existing test patterns in `file:tests/api/`. This approach leverages existing infrastructure without introducing new dependencies or architectural changes. The implementation is designed to unblock dependent tickets #271 (Git Commit UI), #272 (PR Creation API), and #279 (Git Merge API).

## Implementation Steps

### 1. Create Git Router Module

**File**: `file:codeframe/ui/routers/git.py`

Create a new router with the following endpoints:

- **POST `/api/projects/{project_id}/git/branches`** - Create feature branch
  - Extract `issue_number` and `issue_title` from request body
  - Get project from database and verify it exists
  - Check authorization with `db.user_has_project_access(current_user.id, project_id)`
  - Get workspace path from project
  - Initialize `GitWorkflowManager(workspace_path, db)`
  - Call `workflow_manager.create_feature_branch(issue_number, issue_title)`
  - Broadcast `branch_created` event via WebSocket
  - Return branch details: `{branch_name, issue_number, created_at, status: "active"}`

- **GET `/api/projects/{project_id}/git/branches`** - List branches
  - Verify project exists and check authorization
  - Query database using `db.git_branches.get_branches_by_status("active")` filtered by project's issues
  - Return list of branches with: `{id, branch_name, issue_id, status, created_at, merged_at, merge_commit}`

- **GET `/api/projects/{project_id}/git/branches/{branch_name}`** - Get branch details
  - Verify project exists and check authorization
  - Query database for branch by name
  - Verify branch belongs to an issue in this project
  - Return branch details with associated issue information

- **POST `/api/projects/{project_id}/git/commit`** - Commit changes
  - Extract `task_id`, `files_modified`, `agent_id` from request body
  - Verify project exists and check authorization
  - Get task from database and verify it belongs to project
  - Get workspace path and initialize `GitWorkflowManager`
  - Call `workflow_manager.commit_task_changes(task, files_modified, agent_id)`
  - Call `broadcast_commit_created()` with commit details
  - Return commit details: `{commit_hash, commit_message, files_changed, timestamp}`

- **GET `/api/projects/{project_id}/git/commits`** - List commits
  - Verify project exists and check authorization
  - Get workspace path and initialize `GitWorkflowManager`
  - Use `workflow_manager.repo.iter_commits()` from GitPython to get commit history
  - Support query parameters: `branch` (default: current), `limit` (default: 50, max: 100)
  - Return list of commits: `{hash, short_hash, message, author, timestamp, files_changed}`

- **GET `/api/projects/{project_id}/git/status`** - Get working tree status
  - Verify project exists and check authorization
  - Get workspace path and initialize `GitWorkflowManager`
  - Call `workflow_manager.get_current_branch()`
  - Use `workflow_manager.repo.is_dirty()` and `workflow_manager.repo.untracked_files`
  - Return status: `{current_branch, is_dirty, modified_files, untracked_files, staged_files}`

**Dependencies and imports**:
```python
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional
from pathlib import Path
from codeframe.persistence.database import Database
from codeframe.ui.dependencies import get_db
from codeframe.auth.dependencies import get_current_user
from codeframe.auth.models import User
from codeframe.git.workflow_manager import GitWorkflowManager
from codeframe.ui.shared import manager
from codeframe.ui.websocket_broadcasts import broadcast_branch_created, broadcast_commit_created
import git
```

**Request/Response Models**:
- `BranchCreateRequest`: `issue_number: str`, `issue_title: str`
- `BranchResponse`: `id: int`, `branch_name: str`, `issue_id: int`, `status: str`, `created_at: str`, `merged_at: Optional[str]`, `merge_commit: Optional[str]`
- `CommitRequest`: `task_id: int`, `files_modified: List[str]`, `agent_id: str`
- `CommitResponse`: `commit_hash: str`, `commit_message: str`, `files_changed: int`, `timestamp: str`
- `GitStatusResponse`: `current_branch: str`, `is_dirty: bool`, `modified_files: List[str]`, `untracked_files: List[str]`, `staged_files: List[str]`
- `CommitListResponse`: `hash: str`, `short_hash: str`, `message: str`, `author: str`, `timestamp: str`, `files_changed: int`

### 2. Add WebSocket Broadcast Helper

**File**: `file:codeframe/ui/websocket_broadcasts.py`

Add new function after the existing `broadcast_commit_created` function (around line 237):

```python
async def broadcast_branch_created(
    manager,
    project_id: int,
    branch_name: str,
    issue_number: str,
    issue_id: Optional[int] = None,
) -> None:
    """
    Broadcast git branch creation to connected clients.
    
    Args:
        manager: ConnectionManager instance
        project_id: Project ID
        branch_name: Git branch name created
        issue_number: Issue number the branch is for
        issue_id: Optional issue ID
    """
    message = {
        "type": "branch_created",
        "project_id": project_id,
        "branch_name": branch_name,
        "issue_number": issue_number,
        "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
    }
    
    if issue_id is not None:
        message["issue_id"] = issue_id
    
    try:
        await manager.broadcast(message, project_id=project_id)
        logger.debug(f"Broadcast branch_created: {branch_name} for issue {issue_number}")
    except Exception as e:
        logger.error(f"Failed to broadcast branch creation: {e}")
```

This function follows the same pattern as `broadcast_commit_created` and integrates with the existing WebSocket infrastructure.

### 3. Register Router in Server

**File**: `file:codeframe/ui/server.py`

Add import at line 20 (with other router imports):
```python
from codeframe.ui.routers import (
    agents,
    blockers,
    chat,
    checkpoints,
    context,
    discovery,
    git,  # Add this line
    lint,
    metrics,
    projects,
    quality_gates,
    review,
    session,
    tasks,
    websocket,
)
```

Add router registration at line 342 (after other routers, before auth_router):
```python
app.include_router(git.router)
```

### 4. Create Integration Tests

**File**: `file:tests/api/test_git_api.py`

Create comprehensive integration tests covering:

**Test Class**: `TestGitBranchesAPI`
- `test_create_branch_success` - Create branch with valid issue
- `test_create_branch_unauthorized` - Verify 403 when user lacks project access
- `test_create_branch_project_not_found` - Verify 404 for non-existent project
- `test_create_branch_duplicate` - Verify error when branch already exists
- `test_list_branches` - List all branches for project
- `test_list_branches_empty` - List branches when none exist
- `test_get_branch_details` - Get specific branch by name
- `test_get_branch_not_found` - Verify 404 for non-existent branch
- `test_create_branch_broadcasts_websocket` - Verify branch_created event is broadcast

**Test Class**: `TestGitCommitsAPI`
- `test_commit_changes_success` - Commit with valid task and files
- `test_commit_changes_unauthorized` - Verify 403 when user lacks access
- `test_commit_changes_no_files` - Verify error when files_modified is empty
- `test_commit_changes_broadcasts_websocket` - Verify commit_created event is broadcast
- `test_list_commits` - List commits with default parameters
- `test_list_commits_with_limit` - List commits with custom limit
- `test_list_commits_empty_repo` - Handle empty repository gracefully

**Test Class**: `TestGitStatusAPI`
- `test_get_status_clean` - Get status when working tree is clean
- `test_get_status_with_changes` - Get status with modified files
- `test_get_status_unauthorized` - Verify 403 when user lacks access

**Test utilities**:
- Use `api_client` fixture from `file:tests/api/conftest.py`
- Create helper function to set up test project with git repository
- Create helper function to create test issues and tasks
- Use real git operations for integration tests (not mocked)
- Ensure test repositories are cleaned up after each test

**Example test structure**:
```python
import pytest
from fastapi.testclient import TestClient

class TestGitBranchesAPI:
    def test_create_branch_success(self, api_client: TestClient, test_project, test_issue):
        # When: POST /api/projects/{id}/git/branches
        response = api_client.post(
            f"/api/projects/{test_project['id']}/git/branches",
            json={"issue_number": test_issue['issue_number'], "issue_title": test_issue['title']}
        )
        # Then: Assert 201, branch created
        assert response.status_code == 201
        assert response.json()["branch_name"].startswith("issue-")
        
    def test_list_branches(self, api_client: TestClient, test_project):
        # When: GET /api/projects/{id}/git/branches
        response = api_client.get(f"/api/projects/{test_project['id']}/git/branches")
        # Then: Assert 200, correct branch list returned
        assert response.status_code == 200
        assert isinstance(response.json(), list)
```

### 5. Update Dependencies Helper (Optional Enhancement)

**File**: `file:codeframe/ui/dependencies.py`

Consider adding a helper to get `GitWorkflowManager` instance:

```python
def get_git_workflow_manager(
    project_id: int,
    db: Database = Depends(get_db),
) -> GitWorkflowManager:
    """Get GitWorkflowManager for a project.
    
    Args:
        project_id: Project ID
        db: Database instance
        
    Returns:
        GitWorkflowManager instance for the project
        
    Raises:
        HTTPException: If project not found or has no workspace
    """
    project = db.get_project(project_id)
    if not project:
        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
    
    workspace_path = project.get("workspace_path")
    if not workspace_path:
        raise HTTPException(status_code=400, detail="Project has no workspace")
    
    return GitWorkflowManager(Path(workspace_path), db)
```

This can simplify endpoint implementations by reducing boilerplate and ensuring consistent error handling.

## Sequence Diagram

```mermaid
sequenceDiagram
    participant Client
    participant GitRouter
    participant Auth
    participant Database
    participant GitWorkflowManager
    participant GitRepo
    participant WebSocket

    Client->>GitRouter: POST /api/projects/1/git/branches
    GitRouter->>Auth: Verify JWT token
    Auth-->>GitRouter: User authenticated
    GitRouter->>Database: Check user_has_project_access()
    Database-->>GitRouter: Access granted
    GitRouter->>Database: Get project workspace_path
    Database-->>GitRouter: workspace_path
    GitRouter->>GitWorkflowManager: create_feature_branch(issue_number, title)
    GitWorkflowManager->>GitRepo: Create git branch
    GitRepo-->>GitWorkflowManager: Branch created
    GitWorkflowManager->>Database: create_git_branch(issue_id, branch_name)
    Database-->>GitWorkflowManager: Branch ID
    GitWorkflowManager-->>GitRouter: branch_name
    GitRouter->>WebSocket: broadcast_branch_created()
    WebSocket-->>Client: branch_created event
    GitRouter-->>Client: 201 Created {branch_name, status}
```

This sequence applies to all endpoints: authentication is verified first, authorization is checked second, then the git operation is performed, and finally WebSocket events are broadcast.

## Error Handling

All endpoints must handle:
- **403 Forbidden**: User lacks project access (via `user_has_project_access`)
- **404 Not Found**: Project, issue, task, or branch not found
- **400 Bad Request**: Invalid parameters (empty issue_number, no files to commit, etc.)
- **500 Internal Server Error**: Git operations fail (merge conflicts, repository errors)

Use try-except blocks around `GitWorkflowManager` operations to catch `git.GitCommandError` and convert to appropriate HTTP exceptions. Log all errors with context for debugging.

## WebSocket Event Verification

Ensure the following events are properly broadcast:
- **`branch_created`**: When `POST /git/branches` succeeds (new event)
- **`commit_created`**: When `POST /git/commit` succeeds (existing event, verify it fires correctly)

Test WebSocket events in integration tests by subscribing to project updates and verifying messages are received. Use the test broadcast infrastructure in `file:codeframe/ui/server.py` (line 300-318) for testing.

## Blocking Dependencies

This implementation unblocks the following dependent tickets:
- **#271**: Git Commit UI - Requires the commit endpoint and commit_created WebSocket event
- **#272**: PR Creation API - Requires the branches endpoint to list available branches
- **279**: Git Merge API - Requires the branches endpoint and branch status tracking

These endpoints provide the foundational REST API that the dependent features build upon.

---

Execution Information

Branch: main
Commit: a107395

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The codebase has a well-established GitWorkflowManager at file:codeframe/git/workflow_manager.py with methods for branch creation, commits, and merging. The database layer has GitRepository for tracking git operations in the git_branches table. The API follows a consistent pattern using FastAPI routers with authentication via get_current_user and authorization via db.user_has_project_access(). WebSocket broadcasting infrastructure exists in file:codeframe/ui/websocket_broadcasts.py with a broadcast_commit_created function already implemented. The router registration pattern in file:codeframe/ui/server.py is straightforward using app.include_router().

Approach

Create a new git router at file:codeframe/ui/routers/git.py that exposes the existing GitWorkflowManager functionality through REST endpoints. The router will follow the established pattern: project-scoped routes (/api/projects/{project_id}/git/*), authentication/authorization checks, and WebSocket event broadcasting. Add a broadcast_branch_created helper to file:codeframe/ui/websocket_broadcasts.py to complement the existing broadcast_commit_created. Implement comprehensive integration tests following the existing test patterns in file:tests/api/. This approach leverages existing infrastructure without introducing new dependencies or architectural changes.

Implementation Steps

1. Create Git Router Module

File: file:codeframe/ui/routers/git.py

Create a new router with the following endpoints:

• POST /api/projects/{project_id}/git/branches - Create feature branch

  • Extract issue_number and issue_title from request body
  • Get project from database and verify it exists
  • Check authorization with db.user_has_project_access(current_user.id, project_id)
  • Get workspace path from project
  • Initialize GitWorkflowManager(workspace_path, db)
  • Call workflow_manager.create_feature_branch(issue_number, issue_title)
  • Broadcast branch_created event via WebSocket
  • Return branch details: {branch_name, issue_number, created_at, status: "active"}

• GET /api/projects/{project_id}/git/branches - List branches

  • Verify project exists and check authorization
  • Query database using db.get_branches_by_status("active") filtered by project's issues
  • Return list of branches with: {id, branch_name, issue_id, status, created_at, merged_at, merge_commit}

• GET /api/projects/{project_id}/git/branches/{branch_name} - Get branch details

  • Verify project exists and check authorization
  • Query database for branch by name
  • Verify branch belongs to an issue in this project
  • Return branch details with associated issue information

• POST /api/projects/{project_id}/git/commit - Commit changes

  • Extract task_id, files_modified, agent_id from request body
  • Verify project exists and check authorization
  • Get task from database and verify it belongs to project
  • Get workspace path and initialize GitWorkflowManager
  • Call workflow_manager.commit_task_changes(task, files_modified, agent_id)
  • Note: broadcast_commit_created is already called from within the workflow manager or should be called here
  • Return commit details: {commit_hash, commit_message, files_changed, timestamp}

• GET /api/projects/{project_id}/git/commits - List commits

  • Verify project exists and check authorization
  • Get workspace path and initialize GitWorkflowManager
  • Use workflow_manager.repo.iter_commits() from GitPython to get commit history
  • Support query parameters: branch (default: current), limit (default: 50, max: 100)
  • Return list of commits: {hash, short_hash, message, author, timestamp, files_changed}

• GET /api/projects/{project_id}/git/status - Get working tree status

  • Verify project exists and check authorization
  • Get workspace path and initialize GitWorkflowManager
  • Call workflow_manager.get_current_branch()
  • Use workflow_manager.repo.is_dirty() and workflow_manager.repo.untracked_files
  • Return status: {current_branch, is_dirty, modified_files, untracked_files, staged_files}

Dependencies and imports:

from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional
from codeframe.persistence.database import Database
from codeframe.ui.dependencies import get_db
from codeframe.auth.dependencies import get_current_user
from codeframe.auth.models import User
from codeframe.git.workflow_manager import GitWorkflowManager
from codeframe.ui.shared import manager
from codeframe.ui.websocket_broadcasts import broadcast_branch_created, broadcast_commit_created

Request/Response Models:

• BranchCreateRequest: issue_number: str, issue_title: str
• BranchResponse: id: int, branch_name: str, issue_id: int, status: str, created_at: str, merged_at: Optional[str], merge_commit: Optional[str]
• CommitRequest: task_id: int, files_modified: List[str], agent_id: str
• CommitResponse: commit_hash: str, commit_message: str, files_changed: int, timestamp: str
• GitStatusResponse: current_branch: str, is_dirty: bool, modified_files: List[str], untracked_files: List[str], staged_files: List[str]

2. Add WebSocket Broadcast Helper

File: file:codeframe/ui/websocket_broadcasts.py

Add new function after the existing broadcast_commit_created function (around line 237):

async def broadcast_branch_created(
    manager,
    project_id: int,
    branch_name: str,
    issue_number: str,
    issue_id: Optional[int] = None,
) -> None:
    """
    Broadcast git branch creation to connected clients.
    
    Args:
        manager: ConnectionManager instance
        project_id: Project ID
        branch_name: Git branch name created
        issue_number: Issue number the branch is for
        issue_id: Optional issue ID
    """
    message = {
        "type": "branch_created",
        "project_id": project_id,
        "branch_name": branch_name,
        "issue_number": issue_number,
        "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
    }
    
    if issue_id is not None:
        message["issue_id"] = issue_id
    
    try:
        await manager.broadcast(message, project_id=project_id)
        logger.debug(f"Broadcast branch_created: {branch_name} for issue {issue_number}")
    except Exception as e:
        logger.error(f"Failed to broadcast branch creation: {e}")

3. Register Router in Server

File: file:codeframe/ui/server.py

Add import at line 20 (with other router imports):

from codeframe.ui.routers import (
    agents,
    blockers,
    chat,
    checkpoints,
    context,
    discovery,
    git,  # Add this line
    lint,
    metrics,
    ...
)

Add router registration at line 343 (after other routers):

app.include_router(git.router)

4. Create Integration Tests

File: file:tests/api/test_git_api.py

Create comprehensive integration tests covering:

Test Class: TestGitBranchesAPI

• test_create_branch_success - Create branch with valid issue
• test_create_branch_unauthorized - Verify 403 when user lacks project access
• test_create_branch_project_not_found - Verify 404 for non-existent project
• test_create_branch_duplicate - Verify error when branch already exists
• test_list_branches - List all branches for project
• test_list_branches_empty - List branches when none exist
• test_get_branch_details - Get specific branch by name
• test_get_branch_not_found - Verify 404 for non-existent branch

Test Class: TestGitCommitsAPI

• test_commit_changes_success - Commit with valid task and files
• test_commit_changes_unauthorized - Verify 403 when user lacks access
• test_commit_changes_no_files - Verify error when files_modified is empty
• test_list_commits - List commits with default parameters
• test_list_commits_with_limit - List commits with custom limit
• test_list_commits_empty_repo - Handle empty repository gracefully

Test Class: TestGitStatusAPI

• test_get_status_clean - Get status when working tree is clean
• test_get_status_with_changes - Get status with modified files
• test_get_status_unauthorized - Verify 403 when user lacks access

Test utilities:

• Use api_client fixture from file:tests/api/conftest.py
• Create helper function to set up test project with git repository
• Create helper function to create test issues and tasks
• Mock or use real git operations depending on test isolation needs

Example test structure:

import pytest
from fastapi.testclient import TestClient

class TestGitBranchesAPI:
    def test_create_branch_success(self, api_client: TestClient):
        # Setup: Create project and issue
        # When: POST /api/projects/{id}/git/branches
        # Then: Assert 201, branch created, WebSocket event sent
        
    def test_list_branches(self, api_client: TestClient):
        # Setup: Create project with multiple branches
        # When: GET /api/projects/{id}/git/branches
        # Then: Assert 200, correct branch list returned

5. Update Dependencies Helper (Optional Enhancement)

File: file:codeframe/ui/dependencies.py

Consider adding a helper to get GitWorkflowManager instance:

def get_git_workflow_manager(
    project_id: int,
    db: Database = Depends(get_db),
    workspace_manager: WorkspaceManager = Depends(get_workspace_manager)
) -> GitWorkflowManager:
    """Get GitWorkflowManager for a project."""
    project = db.get_project(project_id)
    if not project:
        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
    
    workspace_path = project.get("workspace_path")
    if not workspace_path:
        raise HTTPException(status_code=400, detail="Project has no workspace")
    
    return GitWorkflowManager(workspace_path, db)

This can simplify endpoint implementations by reducing boilerplate.

Sequence Diagram

sequenceDiagram
    participant Client
    participant GitRouter
    participant Auth
    participant Database
    participant GitWorkflowManager
    participant GitRepo
    participant WebSocket

    Client->>GitRouter: POST /api/projects/1/git/branches
    GitRouter->>Auth: Verify JWT token
    Auth-->>GitRouter: User authenticated
    GitRouter->>Database: Check user_has_project_access()
    Database-->>GitRouter: Access granted
    GitRouter->>Database: Get project workspace_path
    Database-->>GitRouter: workspace_path
    GitRouter->>GitWorkflowManager: create_feature_branch(issue_number, title)
    GitWorkflowManager->>GitRepo: Create git branch
    GitRepo-->>GitWorkflowManager: Branch created
    GitWorkflowManager->>Database: create_git_branch(issue_id, branch_name)
    Database-->>GitWorkflowManager: Branch ID
    GitWorkflowManager-->>GitRouter: branch_name
    GitRouter->>WebSocket: broadcast_branch_created()
    WebSocket-->>Client: branch_created event
    GitRouter-->>Client: 201 Created {branch_name, status}

Loading

Error Handling

All endpoints must handle:

• 403 Forbidden: User lacks project access (via user_has_project_access)
• 404 Not Found: Project, issue, task, or branch not found
• 400 Bad Request: Invalid parameters (empty issue_number, no files to commit, etc.)
• 500 Internal Server Error: Git operations fail (merge conflicts, repository errors)

Use try-except blocks around GitWorkflowManager operations to catch git.GitCommandError and convert to appropriate HTTP exceptions.

WebSocket Event Verification

Ensure the following events are properly broadcast:

• branch_created: When POST /git/branches succeeds
• commit_created: When POST /git/commit succeeds (verify existing implementation fires correctly)

Test WebSocket events in integration tests by subscribing to project updates and verifying messages are received.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-established `GitWorkflowManager` at `file:codeframe/git/workflow_manager.py` with methods for branch creation, commits, and merging. The database layer has `GitRepository` for tracking git operations in the `git_branches` table. The API follows a consistent pattern using FastAPI routers with authentication via `get_current_user` and authorization via `db.user_has_project_access()`. WebSocket broadcasting infrastructure exists in `file:codeframe/ui/websocket_broadcasts.py` with a `broadcast_commit_created` function already implemented. The router registration pattern in `file:codeframe/ui/server.py` is straightforward using `app.include_router()`.

## Approach

Create a new git router at `file:codeframe/ui/routers/git.py` that exposes the existing `GitWorkflowManager` functionality through REST endpoints. The router will follow the established pattern: project-scoped routes (`/api/projects/{project_id}/git/*`), authentication/authorization checks, and WebSocket event broadcasting. Add a `broadcast_branch_created` helper to `file:codeframe/ui/websocket_broadcasts.py` to complement the existing `broadcast_commit_created`. Implement comprehensive integration tests following the existing test patterns in `file:tests/api/`. This approach leverages existing infrastructure without introducing new dependencies or architectural changes.

## Implementation Steps

### 1. Create Git Router Module

**File**: `file:codeframe/ui/routers/git.py`

Create a new router with the following endpoints:

- **POST `/api/projects/{project_id}/git/branches`** - Create feature branch
  - Extract `issue_number` and `issue_title` from request body
  - Get project from database and verify it exists
  - Check authorization with `db.user_has_project_access(current_user.id, project_id)`
  - Get workspace path from project
  - Initialize `GitWorkflowManager(workspace_path, db)`
  - Call `workflow_manager.create_feature_branch(issue_number, issue_title)`
  - Broadcast `branch_created` event via WebSocket
  - Return branch details: `{branch_name, issue_number, created_at, status: "active"}`

- **GET `/api/projects/{project_id}/git/branches`** - List branches
  - Verify project exists and check authorization
  - Query database using `db.get_branches_by_status("active")` filtered by project's issues
  - Return list of branches with: `{id, branch_name, issue_id, status, created_at, merged_at, merge_commit}`

- **GET `/api/projects/{project_id}/git/branches/{branch_name}`** - Get branch details
  - Verify project exists and check authorization
  - Query database for branch by name
  - Verify branch belongs to an issue in this project
  - Return branch details with associated issue information

- **POST `/api/projects/{project_id}/git/commit`** - Commit changes
  - Extract `task_id`, `files_modified`, `agent_id` from request body
  - Verify project exists and check authorization
  - Get task from database and verify it belongs to project
  - Get workspace path and initialize `GitWorkflowManager`
  - Call `workflow_manager.commit_task_changes(task, files_modified, agent_id)`
  - Note: `broadcast_commit_created` is already called from within the workflow manager or should be called here
  - Return commit details: `{commit_hash, commit_message, files_changed, timestamp}`

- **GET `/api/projects/{project_id}/git/commits`** - List commits
  - Verify project exists and check authorization
  - Get workspace path and initialize `GitWorkflowManager`
  - Use `workflow_manager.repo.iter_commits()` from GitPython to get commit history
  - Support query parameters: `branch` (default: current), `limit` (default: 50, max: 100)
  - Return list of commits: `{hash, short_hash, message, author, timestamp, files_changed}`

- **GET `/api/projects/{project_id}/git/status`** - Get working tree status
  - Verify project exists and check authorization
  - Get workspace path and initialize `GitWorkflowManager`
  - Call `workflow_manager.get_current_branch()`
  - Use `workflow_manager.repo.is_dirty()` and `workflow_manager.repo.untracked_files`
  - Return status: `{current_branch, is_dirty, modified_files, untracked_files, staged_files}`

**Dependencies and imports**:
```python
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional
from codeframe.persistence.database import Database
from codeframe.ui.dependencies import get_db
from codeframe.auth.dependencies import get_current_user
from codeframe.auth.models import User
from codeframe.git.workflow_manager import GitWorkflowManager
from codeframe.ui.shared import manager
from codeframe.ui.websocket_broadcasts import broadcast_branch_created, broadcast_commit_created
```

**Request/Response Models**:
- `BranchCreateRequest`: `issue_number: str`, `issue_title: str`
- `BranchResponse`: `id: int`, `branch_name: str`, `issue_id: int`, `status: str`, `created_at: str`, `merged_at: Optional[str]`, `merge_commit: Optional[str]`
- `CommitRequest`: `task_id: int`, `files_modified: List[str]`, `agent_id: str`
- `CommitResponse`: `commit_hash: str`, `commit_message: str`, `files_changed: int`, `timestamp: str`
- `GitStatusResponse`: `current_branch: str`, `is_dirty: bool`, `modified_files: List[str]`, `untracked_files: List[str]`, `staged_files: List[str]`

### 2. Add WebSocket Broadcast Helper

**File**: `file:codeframe/ui/websocket_broadcasts.py`

Add new function after the existing `broadcast_commit_created` function (around line 237):

```python
async def broadcast_branch_created(
    manager,
    project_id: int,
    branch_name: str,
    issue_number: str,
    issue_id: Optional[int] = None,
) -> None:
    """
    Broadcast git branch creation to connected clients.
    
    Args:
        manager: ConnectionManager instance
        project_id: Project ID
        branch_name: Git branch name created
        issue_number: Issue number the branch is for
        issue_id: Optional issue ID
    """
    message = {
        "type": "branch_created",
        "project_id": project_id,
        "branch_name": branch_name,
        "issue_number": issue_number,
        "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
    }
    
    if issue_id is not None:
        message["issue_id"] = issue_id
    
    try:
        await manager.broadcast(message, project_id=project_id)
        logger.debug(f"Broadcast branch_created: {branch_name} for issue {issue_number}")
    except Exception as e:
        logger.error(f"Failed to broadcast branch creation: {e}")
```

### 3. Register Router in Server

**File**: `file:codeframe/ui/server.py`

Add import at line 20 (with other router imports):
```python
from codeframe.ui.routers import (
    agents,
    blockers,
    chat,
    checkpoints,
    context,
    discovery,
    git,  # Add this line
    lint,
    metrics,
    ...
)
```

Add router registration at line 343 (after other routers):
```python
app.include_router(git.router)
```

### 4. Create Integration Tests

**File**: `file:tests/api/test_git_api.py`

Create comprehensive integration tests covering:

**Test Class**: `TestGitBranchesAPI`
- `test_create_branch_success` - Create branch with valid issue
- `test_create_branch_unauthorized` - Verify 403 when user lacks project access
- `test_create_branch_project_not_found` - Verify 404 for non-existent project
- `test_create_branch_duplicate` - Verify error when branch already exists
- `test_list_branches` - List all branches for project
- `test_list_branches_empty` - List branches when none exist
- `test_get_branch_details` - Get specific branch by name
- `test_get_branch_not_found` - Verify 404 for non-existent branch

**Test Class**: `TestGitCommitsAPI`
- `test_commit_changes_success` - Commit with valid task and files
- `test_commit_changes_unauthorized` - Verify 403 when user lacks access
- `test_commit_changes_no_files` - Verify error when files_modified is empty
- `test_list_commits` - List commits with default parameters
- `test_list_commits_with_limit` - List commits with custom limit
- `test_list_commits_empty_repo` - Handle empty repository gracefully

**Test Class**: `TestGitStatusAPI`
- `test_get_status_clean` - Get status when working tree is clean
- `test_get_status_with_changes` - Get status with modified files
- `test_get_status_unauthorized` - Verify 403 when user lacks access

**Test utilities**:
- Use `api_client` fixture from `file:tests/api/conftest.py`
- Create helper function to set up test project with git repository
- Create helper function to create test issues and tasks
- Mock or use real git operations depending on test isolation needs

**Example test structure**:
```python
import pytest
from fastapi.testclient import TestClient

class TestGitBranchesAPI:
    def test_create_branch_success(self, api_client: TestClient):
        # Setup: Create project and issue
        # When: POST /api/projects/{id}/git/branches
        # Then: Assert 201, branch created, WebSocket event sent
        
    def test_list_branches(self, api_client: TestClient):
        # Setup: Create project with multiple branches
        # When: GET /api/projects/{id}/git/branches
        # Then: Assert 200, correct branch list returned
```

### 5. Update Dependencies Helper (Optional Enhancement)

**File**: `file:codeframe/ui/dependencies.py`

Consider adding a helper to get `GitWorkflowManager` instance:

```python
def get_git_workflow_manager(
    project_id: int,
    db: Database = Depends(get_db),
    workspace_manager: WorkspaceManager = Depends(get_workspace_manager)
) -> GitWorkflowManager:
    """Get GitWorkflowManager for a project."""
    project = db.get_project(project_id)
    if not project:
        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
    
    workspace_path = project.get("workspace_path")
    if not workspace_path:
        raise HTTPException(status_code=400, detail="Project has no workspace")
    
    return GitWorkflowManager(workspace_path, db)
```

This can simplify endpoint implementations by reducing boilerplate.

## Sequence Diagram

```mermaid
sequenceDiagram
    participant Client
    participant GitRouter
    participant Auth
    participant Database
    participant GitWorkflowManager
    participant GitRepo
    participant WebSocket

    Client->>GitRouter: POST /api/projects/1/git/branches
    GitRouter->>Auth: Verify JWT token
    Auth-->>GitRouter: User authenticated
    GitRouter->>Database: Check user_has_project_access()
    Database-->>GitRouter: Access granted
    GitRouter->>Database: Get project workspace_path
    Database-->>GitRouter: workspace_path
    GitRouter->>GitWorkflowManager: create_feature_branch(issue_number, title)
    GitWorkflowManager->>GitRepo: Create git branch
    GitRepo-->>GitWorkflowManager: Branch created
    GitWorkflowManager->>Database: create_git_branch(issue_id, branch_name)
    Database-->>GitWorkflowManager: Branch ID
    GitWorkflowManager-->>GitRouter: branch_name
    GitRouter->>WebSocket: broadcast_branch_created()
    WebSocket-->>Client: branch_created event
    GitRouter-->>Client: 201 Created {branch_name, status}
```

## Error Handling

All endpoints must handle:
- **403 Forbidden**: User lacks project access (via `user_has_project_access`)
- **404 Not Found**: Project, issue, task, or branch not found
- **400 Bad Request**: Invalid parameters (empty issue_number, no files to commit, etc.)
- **500 Internal Server Error**: Git operations fail (merge conflicts, repository errors)

Use try-except blocks around `GitWorkflowManager` operations to catch `git.GitCommandError` and convert to appropriate HTTP exceptions.

## WebSocket Event Verification

Ensure the following events are properly broadcast:
- **`branch_created`**: When `POST /git/branches` succeeds
- **`commit_created`**: When `POST /git/commit` succeeds (verify existing implementation fires correctly)

Test WebSocket events in integration tests by subscribing to project updates and verifying messages are received.

---

Execution Information

Branch: main
Commit: a107395

New Plan

Observations

The codebase has a well-established GitWorkflowManager at file:codeframe/git/workflow_manager.py with methods for branch creation, commits, and merging. The database layer has GitRepository for tracking git operations in the git_branches table. The API follows a consistent pattern using FastAPI routers with authentication via get_current_user and authorization via db.user_has_project_access(). WebSocket broadcasting infrastructure exists in file:codeframe/ui/websocket_broadcasts.py with a broadcast_commit_created function already implemented. The router registration pattern in file:codeframe/ui/server.py is straightforward using app.include_router().

Approach

Create a new git router at file:codeframe/ui/routers/git.py that exposes the existing GitWorkflowManager functionality through REST endpoints. The router will follow the established pattern: project-scoped routes (/api/projects/{project_id}/git/*), authentication/authorization checks, and WebSocket event broadcasting. Add a broadcast_branch_created helper to file:codeframe/ui/websocket_broadcasts.py to complement the existing broadcast_commit_created. Implement comprehensive integration tests following the existing test patterns in file:tests/api/. This approach leverages existing infrastructure without introducing new dependencies or architectural changes. The implementation is designed to unblock dependent tickets #271 (Git Commit UI), #272 (PR Creation API), and #279 (Git Merge API).

Implementation Steps

1. Create Git Router Module

File: file:codeframe/ui/routers/git.py

Create a new router with the following endpoints:

• POST /api/projects/{project_id}/git/branches - Create feature branch

  • Extract issue_number and issue_title from request body
  • Get project from database and verify it exists
  • Check authorization with db.user_has_project_access(current_user.id, project_id)
  • Get workspace path from project
  • Initialize GitWorkflowManager(workspace_path, db)
  • Call workflow_manager.create_feature_branch(issue_number, issue_title)
  • Broadcast branch_created event via WebSocket
  • Return branch details: {branch_name, issue_number, created_at, status: "active"}

• GET /api/projects/{project_id}/git/branches - List branches

  • Verify project exists and check authorization
  • Query database using db.git_branches.get_branches_by_status("active") filtered by project's issues
  • Return list of branches with: {id, branch_name, issue_id, status, created_at, merged_at, merge_commit}

• GET /api/projects/{project_id}/git/branches/{branch_name} - Get branch details

  • Verify project exists and check authorization
  • Query database for branch by name
  • Verify branch belongs to an issue in this project
  • Return branch details with associated issue information

• POST /api/projects/{project_id}/git/commit - Commit changes

  • Extract task_id, files_modified, agent_id from request body
  • Verify project exists and check authorization
  • Get task from database and verify it belongs to project
  • Get workspace path and initialize GitWorkflowManager
  • Call workflow_manager.commit_task_changes(task, files_modified, agent_id)
  • Call broadcast_commit_created() with commit details
  • Return commit details: {commit_hash, commit_message, files_changed, timestamp}

• GET /api/projects/{project_id}/git/commits - List commits

  • Verify project exists and check authorization
  • Get workspace path and initialize GitWorkflowManager
  • Use workflow_manager.repo.iter_commits() from GitPython to get commit history
  • Support query parameters: branch (default: current), limit (default: 50, max: 100)
  • Return list of commits: {hash, short_hash, message, author, timestamp, files_changed}

• GET /api/projects/{project_id}/git/status - Get working tree status

  • Verify project exists and check authorization
  • Get workspace path and initialize GitWorkflowManager
  • Call workflow_manager.get_current_branch()
  • Use workflow_manager.repo.is_dirty() and workflow_manager.repo.untracked_files
  • Return status: {current_branch, is_dirty, modified_files, untracked_files, staged_files}

Dependencies and imports:

from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional
from pathlib import Path
from codeframe.persistence.database import Database
from codeframe.ui.dependencies import get_db
from codeframe.auth.dependencies import get_current_user
from codeframe.auth.models import User
from codeframe.git.workflow_manager import GitWorkflowManager
from codeframe.ui.shared import manager
from codeframe.ui.websocket_broadcasts import broadcast_branch_created, broadcast_commit_created
import git

Request/Response Models:

• BranchCreateRequest: issue_number: str, issue_title: str
• BranchResponse: id: int, branch_name: str, issue_id: int, status: str, created_at: str, merged_at: Optional[str], merge_commit: Optional[str]
• CommitRequest: task_id: int, files_modified: List[str], agent_id: str
• CommitResponse: commit_hash: str, commit_message: str, files_changed: int, timestamp: str
• GitStatusResponse: current_branch: str, is_dirty: bool, modified_files: List[str], untracked_files: List[str], staged_files: List[str]
• CommitListResponse: hash: str, short_hash: str, message: str, author: str, timestamp: str, files_changed: int

2. Add WebSocket Broadcast Helper

File: file:codeframe/ui/websocket_broadcasts.py

Add new function after the existing broadcast_commit_created function (around line 237):

async def broadcast_branch_created(
    manager,
    project_id: int,
    branch_name: str,
    issue_number: str,
    issue_id: Optional[int] = None,
) -> None:
    """
    Broadcast git branch creation to connected clients.
    
    Args:
        manager: ConnectionManager instance
        project_id: Project ID
        branch_name: Git branch name created
        issue_number: Issue number the branch is for
        issue_id: Optional issue ID
    """
    message = {
        "type": "branch_created",
        "project_id": project_id,
        "branch_name": branch_name,
        "issue_number": issue_number,
        "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
    }
    
    if issue_id is not None:
        message["issue_id"] = issue_id
    
    try:
        await manager.broadcast(message, project_id=project_id)
        logger.debug(f"Broadcast branch_created: {branch_name} for issue {issue_number}")
    except Exception as e:
        logger.error(f"Failed to broadcast branch creation: {e}")

This function follows the same pattern as broadcast_commit_created and integrates with the existing WebSocket infrastructure.

3. Register Router in Server

File: file:codeframe/ui/server.py

Add import at line 20 (with other router imports):

from codeframe.ui.routers import (
    agents,
    blockers,
    chat,
    checkpoints,
    context,
    discovery,
    git,  # Add this line
    lint,
    metrics,
    projects,
    quality_gates,
    review,
    session,
    tasks,
    websocket,
)

Add router registration at line 342 (after other routers, before auth_router):

app.include_router(git.router)

4. Create Integration Tests

File: file:tests/api/test_git_api.py

Create comprehensive integration tests covering:

Test Class: TestGitBranchesAPI

• test_create_branch_success - Create branch with valid issue
• test_create_branch_unauthorized - Verify 403 when user lacks project access
• test_create_branch_project_not_found - Verify 404 for non-existent project
• test_create_branch_duplicate - Verify error when branch already exists
• test_list_branches - List all branches for project
• test_list_branches_empty - List branches when none exist
• test_get_branch_details - Get specific branch by name
• test_get_branch_not_found - Verify 404 for non-existent branch
• test_create_branch_broadcasts_websocket - Verify branch_created event is broadcast

Test Class: TestGitCommitsAPI

• test_commit_changes_success - Commit with valid task and files
• test_commit_changes_unauthorized - Verify 403 when user lacks access
• test_commit_changes_no_files - Verify error when files_modified is empty
• test_commit_changes_broadcasts_websocket - Verify commit_created event is broadcast
• test_list_commits - List commits with default parameters
• test_list_commits_with_limit - List commits with custom limit
• test_list_commits_empty_repo - Handle empty repository gracefully

Test Class: TestGitStatusAPI

• test_get_status_clean - Get status when working tree is clean
• test_get_status_with_changes - Get status with modified files
• test_get_status_unauthorized - Verify 403 when user lacks access

Test utilities:

• Use api_client fixture from file:tests/api/conftest.py
• Create helper function to set up test project with git repository
• Create helper function to create test issues and tasks
• Use real git operations for integration tests (not mocked)
• Ensure test repositories are cleaned up after each test

Example test structure:

import pytest
from fastapi.testclient import TestClient

class TestGitBranchesAPI:
    def test_create_branch_success(self, api_client: TestClient, test_project, test_issue):
        # When: POST /api/projects/{id}/git/branches
        response = api_client.post(
            f"/api/projects/{test_project['id']}/git/branches",
            json={"issue_number": test_issue['issue_number'], "issue_title": test_issue['title']}
        )
        # Then: Assert 201, branch created
        assert response.status_code == 201
        assert response.json()["branch_name"].startswith("issue-")
        
    def test_list_branches(self, api_client: TestClient, test_project):
        # When: GET /api/projects/{id}/git/branches
        response = api_client.get(f"/api/projects/{test_project['id']}/git/branches")
        # Then: Assert 200, correct branch list returned
        assert response.status_code == 200
        assert isinstance(response.json(), list)

5. Update Dependencies Helper (Optional Enhancement)

File: file:codeframe/ui/dependencies.py

Consider adding a helper to get GitWorkflowManager instance:

def get_git_workflow_manager(
    project_id: int,
    db: Database = Depends(get_db),
) -> GitWorkflowManager:
    """Get GitWorkflowManager for a project.
    
    Args:
        project_id: Project ID
        db: Database instance
        
    Returns:
        GitWorkflowManager instance for the project
        
    Raises:
        HTTPException: If project not found or has no workspace
    """
    project = db.get_project(project_id)
    if not project:
        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
    
    workspace_path = project.get("workspace_path")
    if not workspace_path:
        raise HTTPException(status_code=400, detail="Project has no workspace")
    
    return GitWorkflowManager(Path(workspace_path), db)

This can simplify endpoint implementations by reducing boilerplate and ensuring consistent error handling.

Sequence Diagram

sequenceDiagram
    participant Client
    participant GitRouter
    participant Auth
    participant Database
    participant GitWorkflowManager
    participant GitRepo
    participant WebSocket

    Client->>GitRouter: POST /api/projects/1/git/branches
    GitRouter->>Auth: Verify JWT token
    Auth-->>GitRouter: User authenticated
    GitRouter->>Database: Check user_has_project_access()
    Database-->>GitRouter: Access granted
    GitRouter->>Database: Get project workspace_path
    Database-->>GitRouter: workspace_path
    GitRouter->>GitWorkflowManager: create_feature_branch(issue_number, title)
    GitWorkflowManager->>GitRepo: Create git branch
    GitRepo-->>GitWorkflowManager: Branch created
    GitWorkflowManager->>Database: create_git_branch(issue_id, branch_name)
    Database-->>GitWorkflowManager: Branch ID
    GitWorkflowManager-->>GitRouter: branch_name
    GitRouter->>WebSocket: broadcast_branch_created()
    WebSocket-->>Client: branch_created event
    GitRouter-->>Client: 201 Created {branch_name, status}

Loading

This sequence applies to all endpoints: authentication is verified first, authorization is checked second, then the git operation is performed, and finally WebSocket events are broadcast.

Error Handling

All endpoints must handle:

• 403 Forbidden: User lacks project access (via user_has_project_access)
• 404 Not Found: Project, issue, task, or branch not found
• 400 Bad Request: Invalid parameters (empty issue_number, no files to commit, etc.)
• 500 Internal Server Error: Git operations fail (merge conflicts, repository errors)

Use try-except blocks around GitWorkflowManager operations to catch git.GitCommandError and convert to appropriate HTTP exceptions. Log all errors with context for debugging.

WebSocket Event Verification

Ensure the following events are properly broadcast:

• branch_created: When POST /git/branches succeeds (new event)
• commit_created: When POST /git/commit succeeds (existing event, verify it fires correctly)

Test WebSocket events in integration tests by subscribing to project updates and verifying messages are received. Use the test broadcast infrastructure in file:codeframe/ui/server.py (line 300-318) for testing.

Blocking Dependencies

This implementation unblocks the following dependent tickets:

• [P0] Frontend: Git commit and branch visualization UI #271: Git Commit UI - Requires the commit endpoint and commit_created WebSocket event
• [P0] Backend: GitHub PR creation and management API #272: PR Creation API - Requires the branches endpoint to list available branches
• 279: Git Merge API - Requires the branches endpoint and branch status tracking

These endpoints provide the foundational REST API that the dependent features build upon.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-established `GitWorkflowManager` at `file:codeframe/git/workflow_manager.py` with methods for branch creation, commits, and merging. The database layer has `GitRepository` for tracking git operations in the `git_branches` table. The API follows a consistent pattern using FastAPI routers with authentication via `get_current_user` and authorization via `db.user_has_project_access()`. WebSocket broadcasting infrastructure exists in `file:codeframe/ui/websocket_broadcasts.py` with a `broadcast_commit_created` function already implemented. The router registration pattern in `file:codeframe/ui/server.py` is straightforward using `app.include_router()`.

## Approach

Create a new git router at `file:codeframe/ui/routers/git.py` that exposes the existing `GitWorkflowManager` functionality through REST endpoints. The router will follow the established pattern: project-scoped routes (`/api/projects/{project_id}/git/*`), authentication/authorization checks, and WebSocket event broadcasting. Add a `broadcast_branch_created` helper to `file:codeframe/ui/websocket_broadcasts.py` to complement the existing `broadcast_commit_created`. Implement comprehensive integration tests following the existing test patterns in `file:tests/api/`. This approach leverages existing infrastructure without introducing new dependencies or architectural changes. The implementation is designed to unblock dependent tickets #271 (Git Commit UI), #272 (PR Creation API), and #279 (Git Merge API).

## Implementation Steps

### 1. Create Git Router Module

**File**: `file:codeframe/ui/routers/git.py`

Create a new router with the following endpoints:

- **POST `/api/projects/{project_id}/git/branches`** - Create feature branch
  - Extract `issue_number` and `issue_title` from request body
  - Get project from database and verify it exists
  - Check authorization with `db.user_has_project_access(current_user.id, project_id)`
  - Get workspace path from project
  - Initialize `GitWorkflowManager(workspace_path, db)`
  - Call `workflow_manager.create_feature_branch(issue_number, issue_title)`
  - Broadcast `branch_created` event via WebSocket
  - Return branch details: `{branch_name, issue_number, created_at, status: "active"}`

- **GET `/api/projects/{project_id}/git/branches`** - List branches
  - Verify project exists and check authorization
  - Query database using `db.git_branches.get_branches_by_status("active")` filtered by project's issues
  - Return list of branches with: `{id, branch_name, issue_id, status, created_at, merged_at, merge_commit}`

- **GET `/api/projects/{project_id}/git/branches/{branch_name}`** - Get branch details
  - Verify project exists and check authorization
  - Query database for branch by name
  - Verify branch belongs to an issue in this project
  - Return branch details with associated issue information

- **POST `/api/projects/{project_id}/git/commit`** - Commit changes
  - Extract `task_id`, `files_modified`, `agent_id` from request body
  - Verify project exists and check authorization
  - Get task from database and verify it belongs to project
  - Get workspace path and initialize `GitWorkflowManager`
  - Call `workflow_manager.commit_task_changes(task, files_modified, agent_id)`
  - Call `broadcast_commit_created()` with commit details
  - Return commit details: `{commit_hash, commit_message, files_changed, timestamp}`

- **GET `/api/projects/{project_id}/git/commits`** - List commits
  - Verify project exists and check authorization
  - Get workspace path and initialize `GitWorkflowManager`
  - Use `workflow_manager.repo.iter_commits()` from GitPython to get commit history
  - Support query parameters: `branch` (default: current), `limit` (default: 50, max: 100)
  - Return list of commits: `{hash, short_hash, message, author, timestamp, files_changed}`

- **GET `/api/projects/{project_id}/git/status`** - Get working tree status
  - Verify project exists and check authorization
  - Get workspace path and initialize `GitWorkflowManager`
  - Call `workflow_manager.get_current_branch()`
  - Use `workflow_manager.repo.is_dirty()` and `workflow_manager.repo.untracked_files`
  - Return status: `{current_branch, is_dirty, modified_files, untracked_files, staged_files}`

**Dependencies and imports**:
```python
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional
from pathlib import Path
from codeframe.persistence.database import Database
from codeframe.ui.dependencies import get_db
from codeframe.auth.dependencies import get_current_user
from codeframe.auth.models import User
from codeframe.git.workflow_manager import GitWorkflowManager
from codeframe.ui.shared import manager
from codeframe.ui.websocket_broadcasts import broadcast_branch_created, broadcast_commit_created
import git
```

**Request/Response Models**:
- `BranchCreateRequest`: `issue_number: str`, `issue_title: str`
- `BranchResponse`: `id: int`, `branch_name: str`, `issue_id: int`, `status: str`, `created_at: str`, `merged_at: Optional[str]`, `merge_commit: Optional[str]`
- `CommitRequest`: `task_id: int`, `files_modified: List[str]`, `agent_id: str`
- `CommitResponse`: `commit_hash: str`, `commit_message: str`, `files_changed: int`, `timestamp: str`
- `GitStatusResponse`: `current_branch: str`, `is_dirty: bool`, `modified_files: List[str]`, `untracked_files: List[str]`, `staged_files: List[str]`
- `CommitListResponse`: `hash: str`, `short_hash: str`, `message: str`, `author: str`, `timestamp: str`, `files_changed: int`

### 2. Add WebSocket Broadcast Helper

**File**: `file:codeframe/ui/websocket_broadcasts.py`

Add new function after the existing `broadcast_commit_created` function (around line 237):

```python
async def broadcast_branch_created(
    manager,
    project_id: int,
    branch_name: str,
    issue_number: str,
    issue_id: Optional[int] = None,
) -> None:
    """
    Broadcast git branch creation to connected clients.
    
    Args:
        manager: ConnectionManager instance
        project_id: Project ID
        branch_name: Git branch name created
        issue_number: Issue number the branch is for
        issue_id: Optional issue ID
    """
    message = {
        "type": "branch_created",
        "project_id": project_id,
        "branch_name": branch_name,
        "issue_number": issue_number,
        "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
    }
    
    if issue_id is not None:
        message["issue_id"] = issue_id
    
    try:
        await manager.broadcast(message, project_id=project_id)
        logger.debug(f"Broadcast branch_created: {branch_name} for issue {issue_number}")
    except Exception as e:
        logger.error(f"Failed to broadcast branch creation: {e}")
```

This function follows the same pattern as `broadcast_commit_created` and integrates with the existing WebSocket infrastructure.

### 3. Register Router in Server

**File**: `file:codeframe/ui/server.py`

Add import at line 20 (with other router imports):
```python
from codeframe.ui.routers import (
    agents,
    blockers,
    chat,
    checkpoints,
    context,
    discovery,
    git,  # Add this line
    lint,
    metrics,
    projects,
    quality_gates,
    review,
    session,
    tasks,
    websocket,
)
```

Add router registration at line 342 (after other routers, before auth_router):
```python
app.include_router(git.router)
```

### 4. Create Integration Tests

**File**: `file:tests/api/test_git_api.py`

Create comprehensive integration tests covering:

**Test Class**: `TestGitBranchesAPI`
- `test_create_branch_success` - Create branch with valid issue
- `test_create_branch_unauthorized` - Verify 403 when user lacks project access
- `test_create_branch_project_not_found` - Verify 404 for non-existent project
- `test_create_branch_duplicate` - Verify error when branch already exists
- `test_list_branches` - List all branches for project
- `test_list_branches_empty` - List branches when none exist
- `test_get_branch_details` - Get specific branch by name
- `test_get_branch_not_found` - Verify 404 for non-existent branch
- `test_create_branch_broadcasts_websocket` - Verify branch_created event is broadcast

**Test Class**: `TestGitCommitsAPI`
- `test_commit_changes_success` - Commit with valid task and files
- `test_commit_changes_unauthorized` - Verify 403 when user lacks access
- `test_commit_changes_no_files` - Verify error when files_modified is empty
- `test_commit_changes_broadcasts_websocket` - Verify commit_created event is broadcast
- `test_list_commits` - List commits with default parameters
- `test_list_commits_with_limit` - List commits with custom limit
- `test_list_commits_empty_repo` - Handle empty repository gracefully

**Test Class**: `TestGitStatusAPI`
- `test_get_status_clean` - Get status when working tree is clean
- `test_get_status_with_changes` - Get status with modified files
- `test_get_status_unauthorized` - Verify 403 when user lacks access

**Test utilities**:
- Use `api_client` fixture from `file:tests/api/conftest.py`
- Create helper function to set up test project with git repository
- Create helper function to create test issues and tasks
- Use real git operations for integration tests (not mocked)
- Ensure test repositories are cleaned up after each test

**Example test structure**:
```python
import pytest
from fastapi.testclient import TestClient

class TestGitBranchesAPI:
    def test_create_branch_success(self, api_client: TestClient, test_project, test_issue):
        # When: POST /api/projects/{id}/git/branches
        response = api_client.post(
            f"/api/projects/{test_project['id']}/git/branches",
            json={"issue_number": test_issue['issue_number'], "issue_title": test_issue['title']}
        )
        # Then: Assert 201, branch created
        assert response.status_code == 201
        assert response.json()["branch_name"].startswith("issue-")
        
    def test_list_branches(self, api_client: TestClient, test_project):
        # When: GET /api/projects/{id}/git/branches
        response = api_client.get(f"/api/projects/{test_project['id']}/git/branches")
        # Then: Assert 200, correct branch list returned
        assert response.status_code == 200
        assert isinstance(response.json(), list)
```

### 5. Update Dependencies Helper (Optional Enhancement)

**File**: `file:codeframe/ui/dependencies.py`

Consider adding a helper to get `GitWorkflowManager` instance:

```python
def get_git_workflow_manager(
    project_id: int,
    db: Database = Depends(get_db),
) -> GitWorkflowManager:
    """Get GitWorkflowManager for a project.
    
    Args:
        project_id: Project ID
        db: Database instance
        
    Returns:
        GitWorkflowManager instance for the project
        
    Raises:
        HTTPException: If project not found or has no workspace
    """
    project = db.get_project(project_id)
    if not project:
        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
    
    workspace_path = project.get("workspace_path")
    if not workspace_path:
        raise HTTPException(status_code=400, detail="Project has no workspace")
    
    return GitWorkflowManager(Path(workspace_path), db)
```

This can simplify endpoint implementations by reducing boilerplate and ensuring consistent error handling.

## Sequence Diagram

```mermaid
sequenceDiagram
    participant Client
    participant GitRouter
    participant Auth
    participant Database
    participant GitWorkflowManager
    participant GitRepo
    participant WebSocket

    Client->>GitRouter: POST /api/projects/1/git/branches
    GitRouter->>Auth: Verify JWT token
    Auth-->>GitRouter: User authenticated
    GitRouter->>Database: Check user_has_project_access()
    Database-->>GitRouter: Access granted
    GitRouter->>Database: Get project workspace_path
    Database-->>GitRouter: workspace_path
    GitRouter->>GitWorkflowManager: create_feature_branch(issue_number, title)
    GitWorkflowManager->>GitRepo: Create git branch
    GitRepo-->>GitWorkflowManager: Branch created
    GitWorkflowManager->>Database: create_git_branch(issue_id, branch_name)
    Database-->>GitWorkflowManager: Branch ID
    GitWorkflowManager-->>GitRouter: branch_name
    GitRouter->>WebSocket: broadcast_branch_created()
    WebSocket-->>Client: branch_created event
    GitRouter-->>Client: 201 Created {branch_name, status}
```

This sequence applies to all endpoints: authentication is verified first, authorization is checked second, then the git operation is performed, and finally WebSocket events are broadcast.

## Error Handling

All endpoints must handle:
- **403 Forbidden**: User lacks project access (via `user_has_project_access`)
- **404 Not Found**: Project, issue, task, or branch not found
- **400 Bad Request**: Invalid parameters (empty issue_number, no files to commit, etc.)
- **500 Internal Server Error**: Git operations fail (merge conflicts, repository errors)

Use try-except blocks around `GitWorkflowManager` operations to catch `git.GitCommandError` and convert to appropriate HTTP exceptions. Log all errors with context for debugging.

## WebSocket Event Verification

Ensure the following events are properly broadcast:
- **`branch_created`**: When `POST /git/branches` succeeds (new event)
- **`commit_created`**: When `POST /git/commit` succeeds (existing event, verify it fires correctly)

Test WebSocket events in integration tests by subscribing to project updates and verifying messages are received. Use the test broadcast infrastructure in `file:codeframe/ui/server.py` (line 300-318) for testing.

## Blocking Dependencies

This implementation unblocks the following dependent tickets:
- **#271**: Git Commit UI - Requires the commit endpoint and commit_created WebSocket event
- **#272**: PR Creation API - Requires the branches endpoint to list available branches
- **279**: Git Merge API - Requires the branches endpoint and branch status tracking

These endpoints provide the foundational REST API that the dependent features build upon.

---

Execution Information

Branch: main
Commit: a107395