[P1] Backend: Add WebSocket events for Git and PR operations

[frankbria]

Problem

Steps 8-10 will need real-time updates but no WebSocket events exist for Git/PR operations.

Current State

• websocket_broadcasts.py has 27 broadcast functions
• Only commit_created exists for git operations
• No events for: branch creation, PR creation, PR merge

Required Events

Git Events

async def broadcast_branch_created(
    project_id: int,
    branch_name: str,
    issue_id: int | None = None
)

async def broadcast_branch_merged(
    project_id: int,
    branch_name: str,
    target_branch: str = "main"
)

PR Events

async def broadcast_pr_created(
    project_id: int,
    pr_number: int,
    title: str,
    branch: str
)

async def broadcast_pr_merged(
    project_id: int,
    pr_number: int,
    merge_commit: str
)

async def broadcast_pr_closed(
    project_id: int,
    pr_number: int,
    reason: str
)

Frontend Integration

Add to websocketMessageMapper.ts:

case 'branch_created':
case 'pr_created':
case 'pr_merged':
  return { type: 'ACTIVITY_ADDED', payload: {...} };

Acceptance Criteria

• All Git/PR events implemented
• Events fire from appropriate API handlers
• Frontend mapper handles all new event types
• Activity feed shows Git/PR updates

Dependencies

• Coordinate with [P0] Backend: Expose Git branch and commit APIs #270 (Git APIs)
• Coordinate with [P0] Backend: GitHub PR creation and management API #272 (PR APIs)

Committee Report Reference

WebSocket Expert rated Steps 9-10 as "Missing" with quote: "No PR-related events exist."

[traycerai]

Plan

Observations

The codebase has a well-established WebSocket infrastructure with 27 broadcast functions in file:codeframe/ui/websocket_broadcasts.py. The existing broadcast_commit_created function (lines 201-236) provides a clear pattern to follow. The frontend mapper in file:web-ui/src/lib/websocketMessageMapper.ts already handles commit_created events by mapping them to ACTIVITY_ADDED actions (lines 229-245), which populate the activity feed. The GitWorkflowManager in file:codeframe/git/workflow_manager.py contains methods like create_feature_branch and merge_to_main that will need to call the new broadcast functions. No PR-related code exists yet, confirming these will be added in issue #272.

Approach

Following the established pattern in websocket_broadcasts.py, you'll add 5 new broadcast functions (3 for Git, 2 for PR operations initially, with broadcast_pr_closed added later). Each function will follow the same structure: accept manager and project_id as first parameters, construct a message dict with type, project_id, timestamp, and event-specific fields, then call manager.broadcast(). On the frontend, you'll extend the switch statement in websocketMessageMapper.ts to map these new event types to ACTIVITY_ADDED actions, ensuring they appear in the activity feed. The broadcast functions will be called from Git/PR API handlers when those are implemented in issues #270 and #272.

Implementation Steps

1. Backend: Add Git WebSocket Broadcast Functions

File: file:codeframe/ui/websocket_broadcasts.py

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

1.1 Add broadcast_branch_created

• Parameters: manager, project_id: int, branch_name: str, issue_id: int | None = None
• Message structure:
  • type: "branch_created"
  • project_id: int
  • branch_name: str
  • issue_id: int | None (optional field, include only if provided)
  • timestamp: ISO 8601 format using datetime.now(UTC).isoformat().replace("+00:00", "Z")
• Error handling: Wrap manager.broadcast() in try/except, log errors with logger.error()
• Debug logging: Log success with logger.debug(f"Broadcast branch_created: {branch_name}")

1.2 Add broadcast_branch_merged

• Parameters: manager, project_id: int, branch_name: str, target_branch: str = "main"
• Message structure:
  • type: "branch_merged"
  • project_id: int
  • branch_name: str
  • target_branch: str
  • timestamp: ISO 8601 format
• Error handling: Same pattern as above
• Debug logging: Log with branch names

1.3 Update module docstring

• Add new message types to the docstring at the top of the file (lines 14-30):
  • branch_created: Branch creation for issues
  • branch_merged: Branch merge to main/target

2. Backend: Add PR WebSocket Broadcast Functions

File: file:codeframe/ui/websocket_broadcasts.py

Add three PR broadcast functions after the Git functions:

2.1 Add broadcast_pr_created

• Parameters: manager, project_id: int, pr_number: int, title: str, branch: str
• Message structure:
  • type: "pr_created"
  • project_id: int
  • pr_number: int
  • title: str
  • branch: str
  • timestamp: ISO 8601 format
• Error handling: Same pattern
• Debug logging: Log with PR number and title

2.2 Add broadcast_pr_merged

• Parameters: manager, project_id: int, pr_number: int, merge_commit: str
• Message structure:
  • type: "pr_merged"
  • project_id: int
  • pr_number: int
  • merge_commit: str (commit SHA)
  • timestamp: ISO 8601 format
• Error handling: Same pattern
• Debug logging: Log with PR number and commit hash

2.3 Add broadcast_pr_closed

• Parameters: manager, project_id: int, pr_number: int, reason: str
• Message structure:
  • type: "pr_closed"
  • project_id: int
  • pr_number: int
  • reason: str (e.g., "declined", "superseded", "abandoned")
  • timestamp: ISO 8601 format
• Error handling: Same pattern
• Debug logging: Log with PR number and reason

2.4 Update module docstring

• Add PR message types to docstring:
  • pr_created: Pull request creation
  • pr_merged: Pull request merge
  • pr_closed: Pull request closed without merge

3. Frontend: Update WebSocket Message Mapper

File: file:web-ui/src/lib/websocketMessageMapper.ts

3.1 Add new case statements

In the mapWebSocketMessageToAction function's switch statement (around line 229), add new cases after the existing commit_created case:

case 'branch_created':
case 'branch_merged':
case 'pr_created':
case 'pr_merged':
case 'pr_closed':

These should follow the same pattern as commit_created - map to ACTIVITY_ADDED action with:

• timestamp: Convert message.timestamp to string
• type: Use message.type as-is (cast to any to avoid type errors)
• agent: Use msg.agent || 'system'
• message: Generate appropriate message based on event data:
  • branch_created: "Created branch {branch_name}"
  • branch_merged: "Merged {branch_name} to {target_branch}"
  • pr_created: "Created PR #{pr_number}: {title}"
  • pr_merged: "Merged PR #{pr_number}"
  • pr_closed: "Closed PR #{pr_number}: {reason}"

4. Integration Points Documentation

Note: These integrations will be implemented in issues #270 and #272, but document where the broadcasts should be called:

4.1 Git API Integration Points (Issue #270)

• GitWorkflowManager.create_feature_branch (line 42 in file:codeframe/git/workflow_manager.py):

  • After successful branch creation (line 85), call broadcast_branch_created
  • Import: from codeframe.ui.websocket_broadcasts import broadcast_branch_created
  • Import: from codeframe.ui.shared import manager
  • Call: await broadcast_branch_created(manager, project_id, branch_name, issue_id)

• GitWorkflowManager.merge_to_main (line 134):

  • After successful merge (line 194), call broadcast_branch_merged
  • Call: await broadcast_branch_merged(manager, project_id, branch_name, "main")

4.2 PR API Integration Points (Issue #272)

• PR Creation Handler (to be created):

  • After GitHub PR creation, call broadcast_pr_created
  • Pass: manager, project_id, pr_number, title, branch

• PR Merge Handler (to be created):

  • After successful PR merge, call broadcast_pr_merged
  • Pass: manager, project_id, pr_number, merge_commit

• PR Close Handler (to be created):

  • When PR is closed without merge, call broadcast_pr_closed
  • Pass: manager, project_id, pr_number, reason

5. Testing Considerations

5.1 Backend Tests

File: file:tests/ui/test_websocket_broadcasts.py

Add test functions following the existing pattern (see test_broadcast_commit_created_basic at line 146):

• test_broadcast_branch_created_basic: Verify message structure
• test_broadcast_branch_created_with_issue: Test with issue_id
• test_broadcast_branch_merged_basic: Verify merge message
• test_broadcast_pr_created_basic: Verify PR creation message
• test_broadcast_pr_merged_basic: Verify PR merge message
• test_broadcast_pr_closed_basic: Verify PR close message
• Error handling tests for each function

5.2 Frontend Tests

File: file:web-ui/__tests__/lib/websocketMessageMapper.test.ts

Add test cases following the pattern at line 310:

• Test each new message type maps to ACTIVITY_ADDED
• Verify payload structure includes correct timestamp, type, agent, and message
• Test with missing optional fields

6. Activity Feed Type Updates

File: file:web-ui/src/types/agentState.ts

Update the ActivityType union type (line 59) to include new event types:

export type ActivityType =
  | 'task_assigned'
  | 'task_completed'
  | 'task_blocked'
  | 'branch_created'
  | 'branch_merged'
  | 'pr_created'
  | 'pr_merged'
  | 'pr_closed'
  // ... existing types

This ensures TypeScript type safety for the new activity types.

Sequence Diagram

sequenceDiagram
    participant API as Git/PR API Handler
    participant WS as WebSocket Broadcasts
    participant Manager as ConnectionManager
    participant Client as Frontend Client
    participant Mapper as Message Mapper
    participant Feed as Activity Feed

    API->>WS: broadcast_branch_created(manager, project_id, branch_name)
    WS->>WS: Construct message dict
    WS->>Manager: broadcast(message, project_id)
    Manager->>Client: Send JSON message
    Client->>Mapper: mapWebSocketMessageToAction(message)
    Mapper->>Mapper: Switch on message.type
    Mapper->>Feed: ACTIVITY_ADDED action
    Feed->>Feed: Update activity feed UI

    Note over API,Feed: Same flow for all 5 new events

Loading

Summary

This implementation adds 5 new WebSocket broadcast functions following the established pattern in websocket_broadcasts.py. The frontend mapper is extended to handle these events by mapping them to ACTIVITY_ADDED actions, ensuring Git and PR operations appear in the activity feed. The broadcast functions will be integrated into Git/PR API handlers in issues #270 and #272. All changes maintain consistency with existing code patterns and include proper error handling, logging, and TypeScript type safety.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-established WebSocket infrastructure with 27 broadcast functions in `file:codeframe/ui/websocket_broadcasts.py`. The existing `broadcast_commit_created` function (lines 201-236) provides a clear pattern to follow. The frontend mapper in `file:web-ui/src/lib/websocketMessageMapper.ts` already handles `commit_created` events by mapping them to `ACTIVITY_ADDED` actions (lines 229-245), which populate the activity feed. The `GitWorkflowManager` in `file:codeframe/git/workflow_manager.py` contains methods like `create_feature_branch` and `merge_to_main` that will need to call the new broadcast functions. No PR-related code exists yet, confirming these will be added in issue #272.

## Approach

Following the established pattern in `websocket_broadcasts.py`, you'll add 5 new broadcast functions (3 for Git, 2 for PR operations initially, with `broadcast_pr_closed` added later). Each function will follow the same structure: accept `manager` and `project_id` as first parameters, construct a message dict with `type`, `project_id`, `timestamp`, and event-specific fields, then call `manager.broadcast()`. On the frontend, you'll extend the switch statement in `websocketMessageMapper.ts` to map these new event types to `ACTIVITY_ADDED` actions, ensuring they appear in the activity feed. The broadcast functions will be called from Git/PR API handlers when those are implemented in issues #270 and #272.

## Implementation Steps

### 1. Backend: Add Git WebSocket Broadcast Functions

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

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

#### 1.1 Add `broadcast_branch_created`
- **Parameters:** `manager`, `project_id: int`, `branch_name: str`, `issue_id: int | None = None`
- **Message structure:**
  - `type`: "branch_created"
  - `project_id`: int
  - `branch_name`: str
  - `issue_id`: int | None (optional field, include only if provided)
  - `timestamp`: ISO 8601 format using `datetime.now(UTC).isoformat().replace("+00:00", "Z")`
- **Error handling:** Wrap `manager.broadcast()` in try/except, log errors with `logger.error()`
- **Debug logging:** Log success with `logger.debug(f"Broadcast branch_created: {branch_name}")`

#### 1.2 Add `broadcast_branch_merged`
- **Parameters:** `manager`, `project_id: int`, `branch_name: str`, `target_branch: str = "main"`
- **Message structure:**
  - `type`: "branch_merged"
  - `project_id`: int
  - `branch_name`: str
  - `target_branch`: str
  - `timestamp`: ISO 8601 format
- **Error handling:** Same pattern as above
- **Debug logging:** Log with branch names

#### 1.3 Update module docstring
- Add new message types to the docstring at the top of the file (lines 14-30):
  - `branch_created`: Branch creation for issues
  - `branch_merged`: Branch merge to main/target

### 2. Backend: Add PR WebSocket Broadcast Functions

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

Add three PR broadcast functions after the Git functions:

#### 2.1 Add `broadcast_pr_created`
- **Parameters:** `manager`, `project_id: int`, `pr_number: int`, `title: str`, `branch: str`
- **Message structure:**
  - `type`: "pr_created"
  - `project_id`: int
  - `pr_number`: int
  - `title`: str
  - `branch`: str
  - `timestamp`: ISO 8601 format
- **Error handling:** Same pattern
- **Debug logging:** Log with PR number and title

#### 2.2 Add `broadcast_pr_merged`
- **Parameters:** `manager`, `project_id: int`, `pr_number: int`, `merge_commit: str`
- **Message structure:**
  - `type`: "pr_merged"
  - `project_id`: int
  - `pr_number`: int
  - `merge_commit`: str (commit SHA)
  - `timestamp`: ISO 8601 format
- **Error handling:** Same pattern
- **Debug logging:** Log with PR number and commit hash

#### 2.3 Add `broadcast_pr_closed`
- **Parameters:** `manager`, `project_id: int`, `pr_number: int`, `reason: str`
- **Message structure:**
  - `type`: "pr_closed"
  - `project_id`: int
  - `pr_number`: int
  - `reason`: str (e.g., "declined", "superseded", "abandoned")
  - `timestamp`: ISO 8601 format
- **Error handling:** Same pattern
- **Debug logging:** Log with PR number and reason

#### 2.4 Update module docstring
- Add PR message types to docstring:
  - `pr_created`: Pull request creation
  - `pr_merged`: Pull request merge
  - `pr_closed`: Pull request closed without merge

### 3. Frontend: Update WebSocket Message Mapper

**File:** `file:web-ui/src/lib/websocketMessageMapper.ts`

#### 3.1 Add new case statements
In the `mapWebSocketMessageToAction` function's switch statement (around line 229), add new cases after the existing `commit_created` case:

```typescript
case 'branch_created':
case 'branch_merged':
case 'pr_created':
case 'pr_merged':
case 'pr_closed':
```

These should follow the same pattern as `commit_created` - map to `ACTIVITY_ADDED` action with:
- `timestamp`: Convert message.timestamp to string
- `type`: Use message.type as-is (cast to `any` to avoid type errors)
- `agent`: Use `msg.agent || 'system'`
- `message`: Generate appropriate message based on event data:
  - `branch_created`: `"Created branch {branch_name}"`
  - `branch_merged`: `"Merged {branch_name} to {target_branch}"`
  - `pr_created`: `"Created PR #{pr_number}: {title}"`
  - `pr_merged`: `"Merged PR #{pr_number}"`
  - `pr_closed`: `"Closed PR #{pr_number}: {reason}"`

### 4. Integration Points Documentation

**Note:** These integrations will be implemented in issues #270 and #272, but document where the broadcasts should be called:

#### 4.1 Git API Integration Points (Issue #270)
- **`GitWorkflowManager.create_feature_branch`** (line 42 in `file:codeframe/git/workflow_manager.py`):
  - After successful branch creation (line 85), call `broadcast_branch_created`
  - Import: `from codeframe.ui.websocket_broadcasts import broadcast_branch_created`
  - Import: `from codeframe.ui.shared import manager`
  - Call: `await broadcast_branch_created(manager, project_id, branch_name, issue_id)`

- **`GitWorkflowManager.merge_to_main`** (line 134):
  - After successful merge (line 194), call `broadcast_branch_merged`
  - Call: `await broadcast_branch_merged(manager, project_id, branch_name, "main")`

#### 4.2 PR API Integration Points (Issue #272)
- **PR Creation Handler** (to be created):
  - After GitHub PR creation, call `broadcast_pr_created`
  - Pass: `manager`, `project_id`, `pr_number`, `title`, `branch`

- **PR Merge Handler** (to be created):
  - After successful PR merge, call `broadcast_pr_merged`
  - Pass: `manager`, `project_id`, `pr_number`, `merge_commit`

- **PR Close Handler** (to be created):
  - When PR is closed without merge, call `broadcast_pr_closed`
  - Pass: `manager`, `project_id`, `pr_number`, `reason`

### 5. Testing Considerations

#### 5.1 Backend Tests
**File:** `file:tests/ui/test_websocket_broadcasts.py`

Add test functions following the existing pattern (see `test_broadcast_commit_created_basic` at line 146):
- `test_broadcast_branch_created_basic`: Verify message structure
- `test_broadcast_branch_created_with_issue`: Test with issue_id
- `test_broadcast_branch_merged_basic`: Verify merge message
- `test_broadcast_pr_created_basic`: Verify PR creation message
- `test_broadcast_pr_merged_basic`: Verify PR merge message
- `test_broadcast_pr_closed_basic`: Verify PR close message
- Error handling tests for each function

#### 5.2 Frontend Tests
**File:** `file:web-ui/__tests__/lib/websocketMessageMapper.test.ts`

Add test cases following the pattern at line 310:
- Test each new message type maps to `ACTIVITY_ADDED`
- Verify payload structure includes correct timestamp, type, agent, and message
- Test with missing optional fields

### 6. Activity Feed Type Updates

**File:** `file:web-ui/src/types/agentState.ts`

Update the `ActivityType` union type (line 59) to include new event types:
```typescript
export type ActivityType =
  | 'task_assigned'
  | 'task_completed'
  | 'task_blocked'
  | 'branch_created'
  | 'branch_merged'
  | 'pr_created'
  | 'pr_merged'
  | 'pr_closed'
  // ... existing types
```

This ensures TypeScript type safety for the new activity types.

## Sequence Diagram

```mermaid
sequenceDiagram
    participant API as Git/PR API Handler
    participant WS as WebSocket Broadcasts
    participant Manager as ConnectionManager
    participant Client as Frontend Client
    participant Mapper as Message Mapper
    participant Feed as Activity Feed

    API->>WS: broadcast_branch_created(manager, project_id, branch_name)
    WS->>WS: Construct message dict
    WS->>Manager: broadcast(message, project_id)
    Manager->>Client: Send JSON message
    Client->>Mapper: mapWebSocketMessageToAction(message)
    Mapper->>Mapper: Switch on message.type
    Mapper->>Feed: ACTIVITY_ADDED action
    Feed->>Feed: Update activity feed UI

    Note over API,Feed: Same flow for all 5 new events
```

## Summary

This implementation adds 5 new WebSocket broadcast functions following the established pattern in `websocket_broadcasts.py`. The frontend mapper is extended to handle these events by mapping them to `ACTIVITY_ADDED` actions, ensuring Git and PR operations appear in the activity feed. The broadcast functions will be integrated into Git/PR API handlers in issues #270 and #272. All changes maintain consistency with existing code patterns and include proper error handling, logging, and TypeScript type safety.

---

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.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#217 - feat(agents): broadcast agent status changes via WebSocket [merged]
#224 - feat(websocket): implement proactive messaging system [merged]
#228 - fix: prevent duplicate task generation button for late-joining users [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[frankbria]

Closing as part of v2 roadmap cleanup. This v1-specific issue is retained with the v1-legacy label as reference material for Phase 3 (Web UI rebuild). See the v2 strategic roadmap for current priorities.