Carlos Florêncio
745 lines
29 KiB
Markdown
745 lines
29 KiB
Markdown
# GitHub Integration Plan
|
|
|
|
## Context
|
|
|
|
Kandev needs GitHub integration to support two automation workflows:
|
|
|
|
1. **PR Monitor** - When an agent creates a PR during a session, poll GitHub for CI failures and review comments. The user manually reviews this data in the session UI and can choose to send specific feedback to the agent for fixing.
|
|
2. **PR Review Queue** - A background service that periodically polls GitHub for PRs awaiting the user's review, creates tasks in a workflow for each, and optionally auto-starts an agent to review them.
|
|
|
|
**Additional requirements**:
|
|
- PRs must be associated with tasks in the DB (show PR icon on task list)
|
|
- Session detail UI: show PR, comments, CI checks, approval status, pending review count, time-pending-review
|
|
- PR analytics/stats: PRs created, reviewed, comments, CI results
|
|
|
|
**Design decisions** (confirmed with user):
|
|
- Auth: `gh` CLI primary (existing `gh auth login`), PAT in secrets as fallback
|
|
- PR detection: Auto-detect from git push events (no manual workflow config)
|
|
- PR monitor: User manually reviews feedback, NOT auto-sent to agent
|
|
- Review queue: Standalone background service with a manual "pull now" topbar button
|
|
- Scope: Full stack (backend + frontend)
|
|
|
|
---
|
|
|
|
## Phase 1: GitHub Client Package
|
|
|
|
**New package**: `apps/backend/internal/github/`
|
|
|
|
### 1.1 `models.go` - Data models
|
|
|
|
```go
|
|
// PR represents a GitHub Pull Request
|
|
type PR struct {
|
|
Number int
|
|
Title string
|
|
URL string
|
|
HTMLURL string
|
|
State string // open, closed, merged
|
|
HeadBranch string
|
|
BaseBranch string
|
|
AuthorLogin string
|
|
RepoOwner string
|
|
RepoName string
|
|
Draft bool
|
|
Mergeable bool
|
|
Additions int
|
|
Deletions int
|
|
CreatedAt time.Time
|
|
UpdatedAt time.Time
|
|
MergedAt *time.Time
|
|
ClosedAt *time.Time
|
|
}
|
|
|
|
// PRReview represents a review on a PR
|
|
type PRReview struct {
|
|
ID int64
|
|
Author string
|
|
State string // APPROVED, CHANGES_REQUESTED, COMMENTED, PENDING, DISMISSED
|
|
Body string
|
|
CreatedAt time.Time
|
|
}
|
|
|
|
// PRComment represents a review comment on specific code
|
|
type PRComment struct {
|
|
ID int64
|
|
Author string
|
|
Body string
|
|
Path string
|
|
Line int
|
|
Side string // LEFT, RIGHT
|
|
CreatedAt time.Time
|
|
UpdatedAt time.Time
|
|
InReplyTo *int64
|
|
}
|
|
|
|
// CheckRun represents a CI check result
|
|
type CheckRun struct {
|
|
Name string
|
|
Status string // queued, in_progress, completed
|
|
Conclusion string // success, failure, neutral, cancelled, timed_out, action_required, skipped
|
|
HTMLURL string
|
|
Output string // summary text
|
|
StartedAt *time.Time
|
|
CompletedAt *time.Time
|
|
}
|
|
|
|
// PRFeedback aggregates all feedback for a PR (fetched live)
|
|
type PRFeedback struct {
|
|
PR *PR
|
|
Reviews []PRReview
|
|
Comments []PRComment
|
|
Checks []CheckRun
|
|
HasIssues bool // true if failing checks or changes_requested
|
|
}
|
|
|
|
// PRWatch tracks active PR monitoring (session → PR)
|
|
type PRWatch struct {
|
|
ID string
|
|
SessionID string
|
|
TaskID string
|
|
Owner string
|
|
Repo string
|
|
PRNumber int
|
|
Branch string
|
|
LastCheckedAt *time.Time
|
|
LastCommentAt *time.Time
|
|
LastCheckStatus string
|
|
CreatedAt time.Time
|
|
UpdatedAt time.Time
|
|
}
|
|
|
|
// ReviewWatch configures periodic polling for PRs needing user's review
|
|
type ReviewWatch struct {
|
|
ID string
|
|
WorkspaceID string
|
|
WorkflowID string
|
|
WorkflowStepID string
|
|
RepoOwner string
|
|
RepoName string
|
|
AgentProfileID string
|
|
ExecutorProfileID string
|
|
Prompt string
|
|
AutoStart bool
|
|
Enabled bool
|
|
PollIntervalSeconds int
|
|
LastPolledAt *time.Time
|
|
CreatedAt time.Time
|
|
UpdatedAt time.Time
|
|
}
|
|
|
|
// GitHubStatus represents GitHub connection status
|
|
type GitHubStatus struct {
|
|
Authenticated bool
|
|
Username string
|
|
AuthMethod string // "gh_cli", "pat", "none"
|
|
}
|
|
```
|
|
|
|
### 1.2 `client.go` - Interface
|
|
|
|
```go
|
|
type Client interface {
|
|
// Auth
|
|
IsAuthenticated(ctx context.Context) (bool, error)
|
|
GetAuthenticatedUser(ctx context.Context) (string, error)
|
|
|
|
// PR queries
|
|
GetPR(ctx context.Context, owner, repo string, number int) (*PR, error)
|
|
FindPRByBranch(ctx context.Context, owner, repo, branch string) (*PR, error)
|
|
ListAuthoredPRs(ctx context.Context, owner, repo string) ([]*PR, error)
|
|
ListReviewRequestedPRs(ctx context.Context, username string) ([]*PR, error)
|
|
|
|
// PR details
|
|
ListPRReviews(ctx context.Context, owner, repo string, number int) ([]PRReview, error)
|
|
ListPRComments(ctx context.Context, owner, repo string, number int, since *time.Time) ([]PRComment, error)
|
|
ListCheckRuns(ctx context.Context, owner, repo, ref string) ([]CheckRun, error)
|
|
|
|
// Aggregated
|
|
GetPRFeedback(ctx context.Context, owner, repo string, number int) (*PRFeedback, error)
|
|
}
|
|
```
|
|
|
|
### 1.3 `gh_client.go` - Primary (gh CLI)
|
|
|
|
Executes `gh` commands:
|
|
- `gh pr list --json number,title,url,headRefName,baseRefName,author,state,createdAt,updatedAt,additions,deletions,isDraft,mergeable`
|
|
- `gh pr view <number> --json reviews,comments`
|
|
- `gh api repos/{owner}/{repo}/commits/{ref}/check-runs`
|
|
- `gh api search/issues?q=type:pr+review-requested:@me+state:open`
|
|
|
|
Detect availability via `gh --version`. Parse JSON stdout.
|
|
|
|
### 1.4 `pat_client.go` - Fallback (PAT via net/http)
|
|
|
|
Uses `GITHUB_TOKEN` secret from secrets store. `Authorization: token <PAT>`. Rate limit header awareness.
|
|
|
|
### 1.5 `factory.go` - Client factory
|
|
|
|
Try `gh` CLI first, fall back to PAT from secrets store.
|
|
|
|
### 1.6 `provider.go` - DI provider
|
|
|
|
Standard `Provide(cfg, log, secretsSvc, db) (*Service, cleanup, error)` pattern.
|
|
|
|
---
|
|
|
|
## Phase 2: Service + Persistence
|
|
|
|
### 2.1 `service.go` - Business logic
|
|
|
|
```go
|
|
type Service struct {
|
|
client Client
|
|
store *Store
|
|
eventBus bus.EventBus
|
|
logger *logger.Logger
|
|
}
|
|
|
|
// PR Watch operations (for PR monitoring)
|
|
func (s *Service) CreatePRWatch(ctx, sessionID, taskID, owner, repo string, prNumber int, branch string) (*PRWatch, error)
|
|
func (s *Service) DeletePRWatch(ctx, id string) error
|
|
func (s *Service) GetPRWatchBySession(ctx, sessionID string) (*PRWatch, error)
|
|
func (s *Service) ListActivePRWatches(ctx) ([]*PRWatch, error)
|
|
|
|
// Task-PR association
|
|
func (s *Service) AssociatePRWithTask(ctx, taskID, owner, repo string, prNumber int, prURL, prTitle, authorLogin string) (*TaskPR, error)
|
|
func (s *Service) GetTaskPR(ctx, taskID string) (*TaskPR, error)
|
|
func (s *Service) ListTaskPRs(ctx, taskIDs []string) (map[string]*TaskPR, error)
|
|
func (s *Service) UpdateTaskPR(ctx, id string, state, mergeState string, ...) error
|
|
|
|
// PR feedback (fetched live, not stored)
|
|
func (s *Service) GetPRFeedback(ctx, owner, repo string, number int) (*PRFeedback, error)
|
|
|
|
// Review Watch operations (for review queue)
|
|
func (s *Service) CreateReviewWatch(ctx, req *CreateReviewWatchRequest) (*ReviewWatch, error)
|
|
func (s *Service) UpdateReviewWatch(ctx, id string, req *UpdateReviewWatchRequest) error
|
|
func (s *Service) DeleteReviewWatch(ctx, id string) error
|
|
func (s *Service) ListReviewWatches(ctx, workspaceID string) ([]*ReviewWatch, error)
|
|
|
|
// Polling
|
|
func (s *Service) CheckPRWatch(ctx, watch *PRWatch) (*PRFeedback, bool, error) // returns hasNewFeedback
|
|
func (s *Service) CheckReviewWatch(ctx, watch *ReviewWatch) ([]*PR, error) // returns new PRs
|
|
|
|
// Manual fetch
|
|
func (s *Service) TriggerReviewCheck(ctx, watchID string) ([]*PR, error)
|
|
func (s *Service) TriggerAllReviewChecks(ctx, workspaceID string) (int, error) // returns count of new PRs found
|
|
|
|
// Status
|
|
func (s *Service) GetStatus(ctx) (*GitHubStatus, error)
|
|
```
|
|
|
|
### 2.2 `store.go` - SQLite persistence
|
|
|
|
Four tables (owned by github package):
|
|
|
|
```sql
|
|
-- Tracks active PR monitoring (session → PR)
|
|
CREATE TABLE IF NOT EXISTS github_pr_watches (
|
|
id TEXT PRIMARY KEY,
|
|
session_id TEXT NOT NULL UNIQUE,
|
|
task_id TEXT NOT NULL,
|
|
owner TEXT NOT NULL,
|
|
repo TEXT NOT NULL,
|
|
pr_number INTEGER NOT NULL,
|
|
branch TEXT NOT NULL,
|
|
last_checked_at DATETIME,
|
|
last_comment_at DATETIME,
|
|
last_check_status TEXT DEFAULT '',
|
|
created_at DATETIME NOT NULL,
|
|
updated_at DATETIME NOT NULL
|
|
);
|
|
|
|
-- Associates a PR with a task (1:1 for now, could be 1:many later)
|
|
-- Used for: PR icon on task list, session detail PR view, stats
|
|
CREATE TABLE IF NOT EXISTS github_task_prs (
|
|
id TEXT PRIMARY KEY,
|
|
task_id TEXT NOT NULL,
|
|
owner TEXT NOT NULL,
|
|
repo TEXT NOT NULL,
|
|
pr_number INTEGER NOT NULL,
|
|
pr_url TEXT NOT NULL,
|
|
pr_title TEXT NOT NULL,
|
|
head_branch TEXT NOT NULL,
|
|
base_branch TEXT NOT NULL,
|
|
author_login TEXT NOT NULL,
|
|
state TEXT NOT NULL DEFAULT 'open', -- open, closed, merged
|
|
review_state TEXT NOT NULL DEFAULT '', -- approved, changes_requested, pending, ''
|
|
checks_state TEXT NOT NULL DEFAULT '', -- success, failure, pending, ''
|
|
review_count INTEGER DEFAULT 0,
|
|
pending_review_count INTEGER DEFAULT 0,
|
|
comment_count INTEGER DEFAULT 0,
|
|
additions INTEGER DEFAULT 0,
|
|
deletions INTEGER DEFAULT 0,
|
|
created_at DATETIME NOT NULL, -- PR creation time on GitHub
|
|
merged_at DATETIME,
|
|
closed_at DATETIME,
|
|
last_synced_at DATETIME,
|
|
updated_at DATETIME NOT NULL,
|
|
UNIQUE(task_id, pr_number)
|
|
);
|
|
|
|
-- Review watch configurations (workspace → repo polling)
|
|
CREATE TABLE IF NOT EXISTS github_review_watches (
|
|
id TEXT PRIMARY KEY,
|
|
workspace_id TEXT NOT NULL,
|
|
workflow_id TEXT NOT NULL,
|
|
workflow_step_id TEXT NOT NULL,
|
|
repo_owner TEXT NOT NULL,
|
|
repo_name TEXT NOT NULL,
|
|
agent_profile_id TEXT NOT NULL,
|
|
executor_profile_id TEXT NOT NULL,
|
|
prompt TEXT DEFAULT '',
|
|
auto_start BOOLEAN DEFAULT 0,
|
|
enabled BOOLEAN DEFAULT 1,
|
|
poll_interval_seconds INTEGER DEFAULT 300,
|
|
last_polled_at DATETIME,
|
|
created_at DATETIME NOT NULL,
|
|
updated_at DATETIME NOT NULL
|
|
);
|
|
|
|
-- Deduplication: which PRs we already created tasks for
|
|
CREATE TABLE IF NOT EXISTS github_review_pr_tasks (
|
|
id TEXT PRIMARY KEY,
|
|
review_watch_id TEXT NOT NULL,
|
|
pr_number INTEGER NOT NULL,
|
|
pr_url TEXT NOT NULL,
|
|
task_id TEXT NOT NULL,
|
|
created_at DATETIME NOT NULL,
|
|
UNIQUE(review_watch_id, pr_number)
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 3: Background Poller
|
|
|
|
### 3.1 `poller.go`
|
|
|
|
Two goroutine loops:
|
|
|
|
**PR Monitor Loop** (every 2 min):
|
|
1. List all active `github_pr_watches`
|
|
2. For each watch, fetch PR feedback (comments + checks) via client
|
|
3. Compare with last known state (last_comment_at, last_check_status)
|
|
4. If new comments or check state changes:
|
|
- Update the `github_task_prs` record (review_state, checks_state, comment_count, etc.)
|
|
- Publish `github.pr_feedback` event to event bus (for UI notification, NOT auto-prompt)
|
|
- Update watch timestamps
|
|
5. Also sync PR state (merged, closed) to `github_task_prs`
|
|
|
|
**Review Queue Loop** (every 5 min, per-watch configurable):
|
|
1. List all enabled `github_review_watches`
|
|
2. For each watch, call `ListReviewRequestedPRs` filtered to the watch's repo
|
|
3. For each PR not already in `github_review_pr_tasks`:
|
|
- Publish `github.new_pr_to_review` event
|
|
- Orchestrator handler creates the task + associates the PR
|
|
|
|
Methods: `Start(ctx)`, `Stop()`, `TriggerReviewCheck(ctx, watchID)`, `TriggerAllReviewChecks(ctx, workspaceID)`.
|
|
|
|
---
|
|
|
|
## Phase 4: Event Bus + Orchestrator Integration
|
|
|
|
### 4.1 New event types
|
|
|
|
**File**: `apps/backend/internal/events/types.go`
|
|
|
|
```go
|
|
// Event types for GitHub integration
|
|
const (
|
|
GitHubPRFeedback = "github.pr_feedback" // PR has new feedback (UI notification only)
|
|
GitHubPRStateChanged = "github.pr_state_changed" // PR state changed (merged, closed, etc.)
|
|
GitHubNewReviewPR = "github.new_pr_to_review" // New PR found needing review
|
|
GitHubWatchEvent = "github.watch.event" // Watch created/deleted
|
|
GitHubTaskPRUpdated = "github.task_pr.updated" // TaskPR record updated (for UI refresh)
|
|
)
|
|
```
|
|
|
|
### 4.2 PR auto-detection from git events
|
|
|
|
**File**: `apps/backend/internal/orchestrator/event_handlers_git.go`
|
|
|
|
In `handleGitStatusUpdate()`, detect push completion:
|
|
- Track per-session state: when `Ahead` goes from `>0` to `0` with a `RemoteBranch` set, a push happened
|
|
- After detecting push, call `githubService.Client().FindPRByBranch()` to check if a PR exists
|
|
- If PR found and no watch exists for this session:
|
|
1. Auto-create `PRWatch` via `githubService.CreatePRWatch()`
|
|
2. Auto-create `TaskPR` association via `githubService.AssociatePRWithTask()`
|
|
3. Publish `github.task_pr.updated` event (so task list shows PR icon)
|
|
|
|
**Lookup chain**:
|
|
- `repoStore.GetTaskSession(sessionID)` → `RepositoryID`
|
|
- `repoStore.GetRepository(repositoryID)` → `ProviderOwner`, `ProviderName`
|
|
- `FindPRByBranch(providerOwner, providerName, branch)`
|
|
|
|
### 4.3 Orchestrator GitHub event handlers
|
|
|
|
**New file**: `apps/backend/internal/orchestrator/event_handlers_github.go`
|
|
|
|
```go
|
|
// handlePRFeedback forwards PR feedback events to the frontend via WS.
|
|
// The user manually decides whether to send feedback to the agent.
|
|
// This does NOT auto-prompt the agent.
|
|
func (s *Service) handlePRFeedback(ctx context.Context, event *bus.Event) {
|
|
// Extract sessionID, feedback summary from event
|
|
// Forward to WS for session UI notification
|
|
// Frontend shows updated PR data in session detail panel
|
|
}
|
|
|
|
// handleNewReviewPR creates a task for a PR needing review.
|
|
func (s *Service) handleNewReviewPR(ctx context.Context, event *bus.Event) {
|
|
// Extract PR data, ReviewWatch config
|
|
// Create task in the watch's workflow at configured step
|
|
// Associate PR with task via githubService.AssociatePRWithTask()
|
|
// Record in github_review_pr_tasks for dedup
|
|
// If auto_start, enqueue the task for agent execution
|
|
}
|
|
```
|
|
|
|
### 4.4 "Send to Agent" action
|
|
|
|
The session detail UI will have a "Send to Agent" button that lets the user compose a message to the agent including selected PR comments and/or CI failures. This uses the existing `PromptTask()` flow — the frontend sends a user message with the selected feedback context embedded.
|
|
|
|
### 4.5 Orchestrator wiring
|
|
|
|
**File**: `apps/backend/internal/orchestrator/service.go`
|
|
- Add `githubService` field + `SetGitHubService()` setter
|
|
- Add `pushTracker sync.Map` for per-session ahead-count tracking
|
|
- Subscribe to `github.pr_feedback` and `github.new_pr_to_review` events in `Start()`
|
|
|
|
**File**: `apps/backend/cmd/kandev/services.go`
|
|
- Add GitHub service to `Services` struct, initialize via `github.Provide()`
|
|
- Wire into orchestrator, start poller
|
|
|
|
**File**: `apps/backend/cmd/kandev/main.go`
|
|
- Register GitHub HTTP routes
|
|
|
|
---
|
|
|
|
## Phase 5: HTTP API
|
|
|
|
### 5.1 `controller.go`
|
|
|
|
**Route group**: `/api/v1/github/`
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/status` | GET | Auth status (username, auth method) |
|
|
| `/prs/authored` | GET | User's open PRs (query: owner, repo) |
|
|
| `/prs/review-requested` | GET | PRs awaiting user's review |
|
|
| `/prs/{owner}/{repo}/{number}` | GET | PR details with full feedback |
|
|
| `/prs/{owner}/{repo}/{number}/checks` | GET | CI check status only |
|
|
| `/prs/{owner}/{repo}/{number}/comments` | GET | PR comments only |
|
|
| `/task-prs` | GET | List task-PR associations (query: task_ids) |
|
|
| `/task-prs/{taskId}` | GET | Get PR association for a task |
|
|
| `/watches/pr` | GET | List active PR watches |
|
|
| `/watches/pr/{id}` | DELETE | Remove a PR watch |
|
|
| `/watches/review` | GET | List review watches (query: workspace_id) |
|
|
| `/watches/review` | POST | Create review watch |
|
|
| `/watches/review/{id}` | PUT | Update review watch |
|
|
| `/watches/review/{id}` | DELETE | Delete review watch |
|
|
| `/watches/review/{id}/trigger` | POST | Manual "pull now" for one watch |
|
|
| `/watches/review/trigger-all` | POST | Trigger all for workspace |
|
|
| `/stats` | GET | PR stats (query: workspace_id, date range) |
|
|
|
|
### 5.2 `handlers.go` - WS handlers
|
|
|
|
| Action | Description |
|
|
|--------|-------------|
|
|
| `github.status` | Auth status |
|
|
| `github.task_prs.list` | Get task-PR associations (batch) |
|
|
| `github.pr_feedback.get` | Get live PR feedback for session |
|
|
| `github.review_watches.list` | List review watches |
|
|
| `github.review_watches.create` | Create review watch |
|
|
| `github.review_watches.update` | Update review watch |
|
|
| `github.review_watches.delete` | Delete review watch |
|
|
| `github.review_watches.trigger` | Trigger single check |
|
|
| `github.review_watches.trigger_all` | Trigger all for workspace |
|
|
|
|
---
|
|
|
|
## Phase 6: Frontend
|
|
|
|
### 6.1 Types: `apps/web/lib/types/github.ts`
|
|
|
|
```typescript
|
|
interface GitHubStatus {
|
|
authenticated: boolean;
|
|
username: string;
|
|
authMethod: 'gh_cli' | 'pat' | 'none';
|
|
}
|
|
|
|
interface GitHubPR {
|
|
number: number; title: string; url: string; htmlUrl: string;
|
|
state: 'open' | 'closed' | 'merged';
|
|
headBranch: string; baseBranch: string;
|
|
authorLogin: string; repoOwner: string; repoName: string;
|
|
draft: boolean; additions: number; deletions: number;
|
|
createdAt: string; updatedAt: string;
|
|
mergedAt: string | null; closedAt: string | null;
|
|
}
|
|
|
|
interface TaskPR {
|
|
id: string; taskId: string;
|
|
owner: string; repo: string; prNumber: number;
|
|
prUrl: string; prTitle: string;
|
|
headBranch: string; baseBranch: string; authorLogin: string;
|
|
state: 'open' | 'closed' | 'merged';
|
|
reviewState: 'approved' | 'changes_requested' | 'pending' | '';
|
|
checksState: 'success' | 'failure' | 'pending' | '';
|
|
reviewCount: number; pendingReviewCount: number; commentCount: number;
|
|
additions: number; deletions: number;
|
|
createdAt: string; mergedAt: string | null; closedAt: string | null;
|
|
lastSyncedAt: string | null;
|
|
}
|
|
|
|
interface PRReview { id: number; author: string; state: string; body: string; createdAt: string; }
|
|
interface PRComment { id: number; author: string; body: string; path: string; line: number; side: string; createdAt: string; inReplyTo: number | null; }
|
|
interface CheckRun { name: string; status: string; conclusion: string; htmlUrl: string; output: string; }
|
|
interface PRFeedback { pr: GitHubPR; reviews: PRReview[]; comments: PRComment[]; checks: CheckRun[]; hasIssues: boolean; }
|
|
|
|
interface PRWatch { id: string; sessionId: string; taskId: string; owner: string; repo: string; prNumber: number; branch: string; lastCheckedAt: string | null; }
|
|
interface ReviewWatch { id: string; workspaceId: string; workflowId: string; workflowStepId: string; repoOwner: string; repoName: string; agentProfileId: string; executorProfileId: string; prompt: string; autoStart: boolean; enabled: boolean; pollIntervalSeconds: number; lastPolledAt: string | null; }
|
|
```
|
|
|
|
### 6.2 API Client: `apps/web/lib/api/domains/github-api.ts`
|
|
|
|
Methods mirroring all HTTP endpoints.
|
|
|
|
### 6.3 Store: `apps/web/lib/state/slices/github/github-slice.ts`
|
|
|
|
Zustand slice:
|
|
- `github.status` - auth status
|
|
- `github.taskPRs.byTaskId` - PR associations per task (for task list PR icon)
|
|
- `github.prWatches.bySessionId` - active PR watches per session
|
|
- `github.reviewWatches.byWorkspaceId` - review watch configs
|
|
|
|
### 6.4 Hooks: `apps/web/hooks/domains/github/`
|
|
|
|
- `use-github-status.ts` - auth status
|
|
- `use-task-pr.ts` - PR association for a task (or batch for task list)
|
|
- `use-pr-feedback.ts` - live PR feedback for session detail
|
|
- `use-review-watches.ts` - CRUD for review watches
|
|
- `use-pr-watch.ts` - PR monitoring status per session
|
|
|
|
### 6.5 Task List: PR Icon
|
|
|
|
**File**: Modify task card/row components to show a PR icon (e.g., git-pull-request icon from lucide) when `taskPR` exists for that task. Color-coded: green (approved/passing), red (changes requested/failing), yellow (pending).
|
|
|
|
### 6.6 Settings Page: `apps/web/app/settings/general/github/page.tsx`
|
|
|
|
- **Connection Status card**: Auth method, username, `gh` CLI availability
|
|
- **Review Watches table**: List watches with repo, workflow, status, last polled
|
|
- **Create/Edit Review Watch dialog**: Repo selector (from workspace repos with `provider: "github"`), workflow+step selector, agent profile, executor profile, custom prompt, auto-start toggle, poll interval, enable/disable
|
|
|
|
### 6.7 Session Detail: PR Info in Topbar + PR Panel
|
|
|
|
**Session topbar** (`apps/web/components/github/pr-session-topbar.tsx`):
|
|
In the session detail topbar (not the kanban topbar), show a compact PR summary when a PR is associated:
|
|
- PR number + link (e.g., `#42`)
|
|
- State badge (open/merged/closed)
|
|
- CI status indicator (green check / red X / yellow spinner)
|
|
- Review status (e.g., "2/3 approved", "changes requested")
|
|
- Comment count badge
|
|
- Clicking opens the full PR detail panel
|
|
|
|
**Full PR detail panel** (`apps/web/components/github/pr-detail-panel.tsx`):
|
|
Expandable/drawer panel accessible from the session topbar:
|
|
- **PR header**: Title, number, link, state badge, draft indicator
|
|
- **Stats bar**: +additions/-deletions, time since created, time pending review
|
|
- **Reviews section**: List of reviews with state (approved/changes_requested), author, body
|
|
- **Pending reviewers**: Who hasn't reviewed yet, how long pending
|
|
- **CI Checks section**: List of check runs with status badge (pass/fail/pending), link to details
|
|
- **Comments section**: Threaded review comments with file path, line number, author
|
|
- **"Send to Agent" button**: Opens a dialog to compose a message to the agent, with checkboxes to include specific comments/CI failures as context. Sends via normal `PromptTask` flow.
|
|
|
|
### 6.8 Kanban Homepage Topbar: Manual Pull Button
|
|
|
|
**Component**: `apps/web/components/github/refresh-reviews-button.tsx`
|
|
|
|
Button in the **kanban/homepage topbar** (NOT the session detail topbar):
|
|
- Triggers `POST /watches/review/trigger-all` for active workspace
|
|
- Shows toast with results ("Found 3 new PRs to review")
|
|
- Only visible when review watches exist for the workspace
|
|
|
|
### 6.9 Stats
|
|
|
|
**Route**: `/api/v1/github/stats` (backend) + stats section in settings or dedicated page
|
|
|
|
**Backend** (`internal/github/stats.go`):
|
|
|
|
```go
|
|
type PRStats struct {
|
|
// Counts
|
|
TotalPRsCreated int // PRs authored by user (from github_task_prs)
|
|
TotalPRsReviewed int // PRs reviewed (tasks from review watches)
|
|
TotalComments int // Total review comments across all PRs
|
|
TotalChecksRun int // Total CI check runs tracked
|
|
|
|
// Rates
|
|
CIPassRate float64 // % of PRs where all checks passed
|
|
ApprovalRate float64 // % of PRs approved on first review cycle
|
|
|
|
// Timing (averages)
|
|
AvgTimeToFirstReview time.Duration // Time from PR creation to first review
|
|
AvgTimeToMerge time.Duration // Time from PR creation to merge
|
|
AvgTimePendingReview time.Duration // Time PRs spent waiting for review
|
|
|
|
// By period (for charts)
|
|
PRsByDay []DailyCount // PRs created per day
|
|
ReviewsByDay []DailyCount // PRs reviewed per day
|
|
CommentsByDay []DailyCount // Comments per day
|
|
}
|
|
|
|
type DailyCount struct {
|
|
Date string `json:"date"` // "2026-02-22"
|
|
Count int `json:"count"`
|
|
}
|
|
```
|
|
|
|
Data sourced from `github_task_prs` table aggregations with date range filtering.
|
|
|
|
**Frontend** (`apps/web/components/github/pr-stats.tsx`):
|
|
- Stats cards: PRs created, reviewed, avg time to merge, CI pass rate
|
|
- Line charts: PRs over time, comments over time
|
|
- Uses `@kandev/ui` Card, Badge for layout
|
|
- Could be embedded in GitHub settings page or as a section in a workspace dashboard
|
|
|
|
---
|
|
|
|
## Files to Create
|
|
|
|
```
|
|
apps/backend/internal/github/
|
|
models.go # Data models (PR, Review, Comment, Check, Watch, TaskPR)
|
|
client.go # Client interface
|
|
gh_client.go # gh CLI implementation
|
|
pat_client.go # PAT HTTP implementation
|
|
factory.go # Client factory (gh CLI → PAT fallback)
|
|
store.go # SQLite persistence (watches, task_prs, dedup)
|
|
service.go # Business logic
|
|
poller.go # Background polling loops
|
|
controller.go # HTTP endpoints
|
|
handlers.go # WS handlers
|
|
provider.go # DI provider
|
|
stats.go # PR analytics queries
|
|
|
|
apps/web/
|
|
lib/types/github.ts
|
|
lib/api/domains/github-api.ts
|
|
lib/state/slices/github/
|
|
index.ts
|
|
github-slice.ts
|
|
hooks/domains/github/
|
|
use-github-status.ts
|
|
use-task-pr.ts
|
|
use-pr-feedback.ts
|
|
use-review-watches.ts
|
|
use-pr-watch.ts
|
|
app/settings/general/github/
|
|
page.tsx
|
|
components/github/
|
|
github-status.tsx
|
|
review-watch-table.tsx
|
|
review-watch-dialog.tsx
|
|
pr-detail-panel.tsx # Session detail PR view (expandable panel)
|
|
pr-session-topbar.tsx # Compact PR info in session topbar
|
|
pr-task-icon.tsx # PR icon for task list
|
|
refresh-reviews-button.tsx # Topbar manual pull button
|
|
send-to-agent-dialog.tsx # Compose feedback to send to agent
|
|
pr-stats.tsx # PR analytics cards + charts
|
|
```
|
|
|
|
## Files to Modify
|
|
|
|
```
|
|
apps/backend/internal/events/types.go # Add GitHub event constants
|
|
apps/backend/internal/orchestrator/service.go # Add githubService field + setter + push tracker
|
|
apps/backend/internal/orchestrator/event_handlers_git.go # PR auto-detection on push
|
|
apps/backend/cmd/kandev/services.go # Wire GitHub service
|
|
apps/backend/cmd/kandev/types.go # Add GitHub to Services struct
|
|
apps/backend/cmd/kandev/main.go # Register GitHub routes
|
|
|
|
apps/web/lib/state/store.ts # Add github slice
|
|
apps/web/lib/state/hydration/merge-strategies.ts # Add github hydration
|
|
apps/web/app/settings/general/ (layout or nav) # Add GitHub settings link
|
|
apps/web/components/ (task card/row) # Add PR icon to task list
|
|
apps/web/components/ (session detail panel) # Add PR detail panel
|
|
```
|
|
|
|
## New file: `apps/backend/internal/orchestrator/event_handlers_github.go`
|
|
|
|
Orchestrator event handlers for GitHub events (handlePRFeedback, handleNewReviewPR).
|
|
|
|
## Key Patterns to Reuse
|
|
|
|
- **Provider pattern**: `Provide(cfg, log, ...) (*Service, cleanup, error)` — see `apps/backend/internal/secrets/provider.go`
|
|
- **Event bus**: `bus.EventBus` publish/subscribe — see `apps/backend/internal/events/types.go`
|
|
- **Setter injection**: `SetGitHubService()` — see `orchestrator/service.go` `SetWorkflowStepGetter()`
|
|
- **Repository sub-interfaces**: Split interfaces in `apps/backend/internal/task/repository/interface.go`
|
|
- **Task service Repos struct**: `taskservice.Repos{}` — see `apps/backend/cmd/kandev/services.go:38`
|
|
- **Git event handling**: `handleGitStatusUpdate()` in `apps/backend/internal/orchestrator/event_handlers_git.go`
|
|
- **Repository model provider fields**: `Provider`, `ProviderOwner`, `ProviderName` in `apps/backend/internal/task/models/models.go:285`
|
|
- **Secrets store for PAT**: `apps/backend/internal/secrets/service.go` (Reveal method)
|
|
- **Credential env provider**: `GITHUB_TOKEN` already listed in `apps/backend/internal/agent/credentials/env_provider.go:25`
|
|
- **WS handler pattern**: See existing handlers in `apps/backend/internal/task/handlers/`
|
|
- **Frontend store slices**: Domain pattern in `apps/web/lib/state/slices/`
|
|
- **Frontend hooks**: Domain pattern in `apps/web/hooks/domains/`
|
|
- **Settings page layout**: Existing pages at `apps/web/app/settings/general/{editors,secrets,notifications}/`
|
|
- **Shadcn components**: Import from `@kandev/ui` — Table, Dialog, Button, Badge, etc.
|
|
|
|
## Implementation Order
|
|
|
|
### Milestone 1: GitHub Client (Backend)
|
|
1. `models.go` - data models
|
|
2. `client.go` - interface
|
|
3. `gh_client.go` - gh CLI implementation
|
|
4. `pat_client.go` - PAT fallback
|
|
5. `factory.go` - client factory
|
|
6. Unit tests for client JSON parsing
|
|
|
|
### Milestone 2: Persistence + Service (Backend)
|
|
7. `store.go` - SQLite tables + CRUD
|
|
8. `service.go` - business logic
|
|
9. `provider.go` - DI provider
|
|
10. Wire into `cmd/kandev/services.go`
|
|
|
|
### Milestone 3: API + Handlers (Backend)
|
|
11. `controller.go` - HTTP endpoints
|
|
12. `handlers.go` - WS handlers
|
|
13. Add event types to `events/types.go`
|
|
14. Wire routes in `cmd/kandev/main.go`
|
|
|
|
### Milestone 4: Poller + Orchestrator (Backend)
|
|
15. `poller.go` - background polling
|
|
16. Push detection in `event_handlers_git.go`
|
|
17. `event_handlers_github.go` - orchestrator GitHub event handlers
|
|
18. Wire GitHub service into orchestrator
|
|
19. Integration tests
|
|
|
|
### Milestone 5: Frontend Core
|
|
20. TypeScript types
|
|
21. API client
|
|
22. Store slice
|
|
23. Domain hooks
|
|
|
|
### Milestone 6: Frontend UI
|
|
24. Settings page (GitHub config + review watches)
|
|
25. Task list PR icon
|
|
26. Session detail PR panel (PR, comments, CI, approvals, "Send to Agent")
|
|
27. Topbar refresh button
|
|
|
|
### Milestone 7: Stats
|
|
28. `stats.go` - PR analytics queries (aggregations on `github_task_prs`)
|
|
29. Stats HTTP endpoint (`/api/v1/github/stats`)
|
|
30. Frontend stats component (`pr-stats.tsx`) with cards + charts
|
|
31. Integrate stats into GitHub settings page or dashboard
|
|
|
|
## Verification
|
|
|
|
1. **Backend unit tests**: Client JSON parsing, store CRUD, poller logic
|
|
2. **Integration**: `make -C apps/backend test`
|
|
3. **Lint/typecheck**: `make -C apps/backend lint` + `cd apps && pnpm --filter @kandev/web typecheck`
|
|
4. **Manual**: Check `/api/v1/github/status`, create review watch, trigger manual pull
|
|
5. **E2E**: Agent pushes → PR auto-detected → PR watch created → task shows PR icon → session detail shows PR panel → user reviews and sends feedback to agent
|