feat: unlink task pull requests (#2114)

This commit is contained in:
Carlos Florêncio
2026-08-02 17:00:32 +01:00
committed by GitHub
parent 554c33f24d
commit a6326fdc5d
38 changed files with 1808 additions and 109 deletions
+187
View File
@@ -0,0 +1,187 @@
---
spec: docs/specs/tasks/link-existing-task-github-issue.md
created: 2026-07-31
status: implemented
---
# Implementation Plan: Unlink A Task GitHub Pull Request
## Overview
Add a workspace-authorized unlink contract for one persisted GitHub task-PR
association, broadcast the removal to connected clients, and expose it through
the existing multi-PR tab strip. The backend lands first so frontend state can
consume a stable API and WebSocket contract; desktop and mobile behavior then
share one mutation path and receive focused Playwright coverage.
## Backend
### Durable association detachment
- Update `apps/backend/internal/github/store.go` and
`apps/backend/internal/github/models.go` so `github_task_prs` gains an
idempotently migrated nullable `detached_at` timestamp on SQLite and
Postgres-compatible startup paths.
- Keep detached rows as durable tombstones so a poller or later session does
not silently rediscover an explicitly removed PR. Active association reads,
task search, review sources, and automation list paths must filter
`detached_at IS NULL`.
- Add an exact association lookup by ID and a workspace-scoped detach mutation.
The mutation stamps only the requested row. Explicit URL linking of the same
`(task_id, repository_id, pr_number)` clears the tombstone; automatic watch
discovery does not.
- Preserve task deletion cleanup and existing task/repository/PR uniqueness.
No GitHub API mutation occurs during detach.
### Service and HTTP contract
- Add a service entry point in
`apps/backend/internal/github/service_pr_watch.go` (or a focused sibling
file) that resolves the association, authorizes its stored workspace, and
detaches it without leaking whether a cross-workspace ID exists.
- Register
`DELETE /api/v1/github/task-prs/:associationId?workspace_id=<workspaceId>` in
`apps/backend/internal/github/controller.go`. Return `{ "deleted": true }`
on success and `404` for unknown or workspace-mismatched associations.
- Publish a typed removal payload containing `workspace_id`, `task_id`, and
`association_id` only after the detach transaction commits.
### Live update contract
- Add `github.task_pr.deleted` to
`apps/backend/internal/events/types.go` and
`apps/backend/pkg/websocket/actions.go`.
- Subscribe it in
`apps/backend/internal/gateway/websocket/task_notifications.go`; the payload's
workspace ID keeps routing scoped to clients for the owning workspace.
## Frontend
### API, store, and live updates
- Add `deleteTaskPR(associationId, workspaceId)` to
`apps/web/lib/api/domains/github-api.ts`.
- Extend the GitHub Zustand slice in
`apps/web/lib/state/slices/github/{types.ts,github-slice.ts}` with
`removeTaskPR(taskId, associationId)`, removing only the selected row and
deleting an empty task bucket.
- Type `github.task_pr.deleted` in `apps/web/lib/types/backend.ts` and handle it
in `apps/web/lib/ws/handlers/github.ts` so other tabs and windows converge.
- Expose a shared unlink mutation from
`apps/web/hooks/domains/github/use-task-pr.ts`. It waits for the HTTP success
before removing local state and reports failure without hiding the PR.
### Multi-PR tab close action
- Refactor `apps/web/components/github/multi-pr-ci-popover.tsx` so the tab label
and close action are sibling semantic buttons rather than nested buttons.
Render the close action only while the task has multiple PRs.
- Give each close action an association-specific accessible name, stop its
pointer/click activation from selecting or opening the PR, disable it while
its request is pending, and retain the tab with an error toast on failure.
- After a successful removal, select/focus a deterministic adjacent remaining
tab when the multi-PR surface remains mounted. When two PRs become one, the
existing parent surface collapses naturally to its single-PR variant and
restores focus to that surviving trigger.
- Wire the same mutation into both
`apps/web/components/github/pr-topbar-button.tsx` and
`apps/web/components/github/pr-status-chip.tsx`.
### Mobile design contract
- **Desktop outcome:** hovering the topbar's multi-PR control shows the existing
tabbed CI popover; each tab has a compact close action.
- **Mobile entry point:** tap the existing PR status chip to open
`PRStatusChipMultiDrawer`; no new route or overlay is introduced.
- **Nearest shipped exemplar:** the current
`PRStatusChipMultiDrawer` + `MultiPRCIPopover` composition supplies the inset
bottom drawer, fixed header, tab hierarchy, and single internally scrolling
body.
- **Hierarchy and action:** the selected PR remains the focal content; unlink is
a secondary action attached to each PR tab. Mobile close targets use an
actual minimum 44px hitbox and an association-specific accessible label.
- **Presentation rationale:** unlink is a short contextual action inside an
already-open status surface, so the existing drawer is more direct than a
second confirmation drawer or route.
- **Shared behavior:** API mutation, pending state, error handling, selected-PR
fallback, and store removal are shared; only responsive geometry differs.
- **Viewport behavior:** retain the drawer's `min-h-0` internal scroll owner,
safe-area behavior, focus return, and zero document-level horizontal
overflow.
## Tests
- **What:** detaching one association is workspace-scoped, persists across a
store reopen/replayed migration, active lists omit it, siblings remain, and
explicit relinking restores it.
**File:** focused tests beside `apps/backend/internal/github/store.go` and
`service_pr_watch.go`.
**How:** table-driven store/service tests using the real test database and a
workspace authorizer.
- **What:** the HTTP endpoint returns success for the owning workspace and
fails closed for unknown/cross-workspace IDs without mutating rows.
**File:** `apps/backend/internal/github/controller_test.go`.
**How:** Gin handler integration tests against the real GitHub store/service.
- **What:** a committed detach broadcasts the typed workspace-scoped removal
notification.
**File:**
`apps/backend/internal/gateway/websocket/task_notifications_test.go`.
**How:** event-bus notification test.
- **What:** API URL/method, exact store removal, WebSocket removal, pending
close state, selected fallback, focus behavior, and failure retention.
**Files:** `apps/web/lib/api/domains/github-api.test.ts`,
`apps/web/lib/state/slices/github/github-slice.test.ts`,
`apps/web/lib/ws/handlers/github.test.ts`, and the focused
`apps/web/components/github/pr-ci-popover.automation.test.tsx`.
**How:** Vitest unit/component tests with mocked API and store state.
## E2E Tests
- **Scenario:** GIVEN a desktop task with two linked PRs, WHEN the user hovers
the topbar PR control and closes the older PR tab, THEN only the newer PR
remains before and after reload.
**File:** `apps/web/e2e/tests/pr/pr-multi-popover.spec.ts`.
**What to verify:** close action is reachable, no sibling tab is removed, the
topbar changes to the single-PR state, and persistence survives reload.
- **Scenario:** GIVEN the same task on a coarse-pointer phone, WHEN the user
opens the PR status drawer and taps one tab's unlink target, THEN the same
association is removed with a touch-sized control and no horizontal page
overflow.
**File:** `apps/web/e2e/tests/pr/mobile-pr-ci-chip.spec.ts`.
**What to verify:** drawer entry, accessible close action, minimum hitbox,
resulting single-PR chip, reload persistence, and document containment.
## Public Documentation
- Update `docs/public/sessions-and-review.md` beside the existing multi-PR
selector guidance. Explain where unlink is available and that it removes the
Kandev association only, leaving the remote PR and branch untouched.
## Implementation Waves And Parallel Candidates
The default execution order is sequential in the primary conversation.
- [x] [Task 01: Backend unlink contract](task-01-backend-unlink-contract.md)
- [x] [Task 02: Frontend multi-PR unlink UI](task-02-frontend-multi-pr-unlink.md)
- [x] [Task 03: Desktop and mobile E2E coverage](task-03-pr-unlink-e2e.md)
- [x] [Task 04: Public documentation](task-04-public-documentation.md)
Tasks 01 and 04 are parallel-safe because they own disjoint implementation and
documentation files, but parallel execution still requires explicit user
authorization. Tasks 02 and 03 are sequential after the backend contract and
UI respectively.
## Risks
- Filtering detached rows must cover every task-PR consumer; a missed query
could leave an old PR visible in search, review, or automation even when the
topbar is correct.
- Automatic PR-watch discovery and explicit manual relinking need different
tombstone behavior so background sync cannot resurrect a user removal while
deliberate relinking still works.
- A close button nested inside the current tab button would produce invalid
interactive markup and broken keyboard behavior; the tab composition must be
split without regressing roving tabindex.
- Removing the selected tab can unmount the multi-PR surface when only one PR
remains, so focus management must tolerate both the retained and collapsed
cases.
@@ -0,0 +1,70 @@
---
id: "01-backend-unlink-contract"
title: "Backend unlink contract"
status: done
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/tasks/link-existing-task-github-issue.md"
---
# Task 01: Backend Unlink Contract
## Acceptance
- One workspace-authorized endpoint detaches exactly one GitHub task-PR
association, leaves sibling associations and the remote PR untouched, and
fails closed for unknown or cross-workspace IDs.
- Detached associations survive restart/migration replay, disappear from all
active association reads and automation inputs, are not resurrected by
automatic watch discovery, and can be restored by explicit URL linking.
- A successful detach publishes a workspace-routed `github.task_pr.deleted`
notification only after persistence succeeds.
## Verification
```bash
cd apps/backend && go test ./internal/github ./internal/gateway/websocket ./pkg/websocket
```
## Files likely touched
- `apps/backend/internal/github/models.go`
- `apps/backend/internal/github/store.go`
- `apps/backend/internal/github/service_pr_watch.go` or a focused sibling
- `apps/backend/internal/github/controller.go`
- `apps/backend/internal/github/*_test.go`
- `apps/backend/internal/events/types.go`
- `apps/backend/pkg/websocket/actions.go`
- `apps/backend/internal/gateway/websocket/task_notifications.go`
- `apps/backend/internal/gateway/websocket/task_notifications_test.go`
## Dependencies
None.
## Parallelism
Parallel-safe with Task 04 only: implementation and public-doc files are
disjoint, and Task 04 does not depend on generated contracts.
## Inputs
- Spec sections: `What`, `Scenarios`, `Data And API`, `Failure Modes`.
- Plan sections: `Durable association detachment`, `Service and HTTP contract`,
`Live update contract`.
- Patterns: GitLab's workspace-scoped `DeleteTaskMRForWorkspace`, GitHub's
`ReplaceTaskPR`, and workspace-routed task notification payloads.
## Risks
- Existing databases and both supported SQL dialects must receive the nullable
column through replay-safe migration order.
- Internal automatic association paths must not clear the tombstone intended
for explicit relinking only.
## Output contract
Report the behavioral tests added, files changed, exact command result,
remaining risks/blockers, and update this task plus `plan.md` status in the same
conversation.
@@ -0,0 +1,75 @@
---
id: "02-frontend-multi-pr-unlink"
title: "Frontend multi-PR unlink UI"
status: done
wave: 2
depends_on: ["01-backend-unlink-contract"]
plan: "plan.md"
spec: "../../specs/tasks/link-existing-task-github-issue.md"
---
# Task 02: Frontend Multi-PR Unlink UI
## Acceptance
- Every tab in a multi-PR desktop popover and mobile drawer has an accessible
unlink button; the label button and close button are valid sibling controls,
and the mobile target is at least 44px.
- Successful unlink removes only the selected association from local state and
live updates do the same in other clients; failure retains the tab and shows
an error.
- Tab selection, roving keyboard navigation, pending state, adjacent fallback,
and the two-to-one PR surface collapse remain deterministic.
## Verification
```bash
cd apps/web && pnpm exec vitest run components/github/pr-ci-popover.automation.test.tsx lib/api/domains/github-api.test.ts lib/state/slices/github/github-slice.test.ts lib/ws/handlers/github.test.ts
cd apps/web && pnpm run typecheck
```
## Files likely touched
- `apps/web/lib/api/domains/github-api.ts`
- `apps/web/lib/api/domains/github-api.test.ts`
- `apps/web/lib/state/slices/github/types.ts`
- `apps/web/lib/state/slices/github/github-slice.ts`
- `apps/web/lib/state/slices/github/github-slice.test.ts`
- `apps/web/lib/types/backend.ts`
- `apps/web/lib/ws/handlers/github.ts`
- `apps/web/lib/ws/handlers/github.test.ts`
- `apps/web/hooks/domains/github/use-task-pr.ts`
- `apps/web/components/github/multi-pr-ci-popover.tsx`
- `apps/web/components/github/pr-ci-popover.automation.test.tsx`
- `apps/web/components/github/pr-topbar-button.tsx`
- `apps/web/components/github/pr-status-chip.tsx`
## Dependencies
Task 01's HTTP and WebSocket contracts.
## Parallelism
Sequential. This task consumes Task 01's exact payload and endpoint shapes and
owns shared GitHub frontend state used by the E2E task.
## Inputs
- Spec scenarios: `Unlink one of several pull requests`, `Keep an association
when unlink fails`, `Reach unlink from a touch device`.
- Plan sections: `API, store, and live updates`, `Multi-PR tab close action`,
`Mobile design contract`.
- Patterns: GitLab `MRTopbarButton` unlink error handling and the existing
`PRStatusChipMultiDrawer` touch composition.
## Risks
- Do not nest an icon button inside the existing `role="tab"` button.
- A successful two-to-one removal can unmount the active multi-PR component;
focus logic must not assume the tablist still exists.
## Output contract
Report the RED/GREEN evidence, files changed, exact command results, mobile
interaction details, remaining risks/blockers, and update this task plus
`plan.md` status in the same conversation.
@@ -0,0 +1,66 @@
---
id: "03-pr-unlink-e2e"
title: "PR unlink E2E coverage"
status: done
wave: 3
depends_on: ["01-backend-unlink-contract", "02-frontend-multi-pr-unlink"]
plan: "plan.md"
spec: "../../specs/tasks/link-existing-task-github-issue.md"
---
# Task 03: PR Unlink E2E Coverage
## Acceptance
- Desktop Playwright coverage unlinks the older of two PRs from the hover
popover and proves the sibling plus persisted single-PR state remain after
reload.
- Mobile Playwright coverage performs the same action through the existing PR
status drawer using a touch event, verifies the close target hitbox, and
proves document containment.
- Shared page-object/API seed helpers identify associations without relying on
unstable visible copy.
## Verification
```bash
cd apps/web && pnpm e2e:run --host --project chromium e2e/tests/pr/pr-multi-popover.spec.ts
cd apps/web && pnpm e2e:run --host --project mobile-chrome e2e/tests/pr/mobile-pr-ci-chip.spec.ts
```
## Files likely touched
- `apps/web/e2e/tests/pr/pr-multi-popover.spec.ts`
- `apps/web/e2e/tests/pr/mobile-pr-ci-chip.spec.ts`
- `apps/web/e2e/pages/session-page.ts`
- `apps/web/e2e/helpers/api-client.ts` only if the existing seed helpers cannot
express the required association identity
## Dependencies
Tasks 01 and 02.
## Parallelism
Sequential. The scenarios exercise the completed backend contract and shared
frontend component.
## Inputs
- Spec scenarios: desktop unlink and coarse-pointer unlink.
- Plan section: `E2E Tests` and the complete mobile design contract.
- Existing seed/open patterns in the two named PR specs.
## Risks
- The mobile project only discovers `mobile-*.spec.ts`; keep the existing file
name and run the managed E2E runner so production frontend/backend artifacts
are rebuilt.
- When the second PR disappears the drawer/popover may unmount; assert the
resulting task state rather than waiting on a detached close control.
## Output contract
Report RED/GREEN Playwright evidence, screenshots or rendered inspection,
files changed, exact command result, remaining risks/blockers, and update this
task plus `plan.md` status in the same conversation.
@@ -0,0 +1,58 @@
---
id: "04-public-documentation"
title: "Public documentation"
status: done
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/tasks/link-existing-task-github-issue.md"
---
# Task 04: Public Documentation
## Acceptance
- The public session/review guide tells desktop and mobile users where the
multi-PR unlink action appears.
- The guide states that unlinking removes only Kandev's association and leaves
the GitHub PR, branch, commits, task repositories, and sibling links intact.
- Public documentation validation passes without navigation or link errors.
## Verification
```bash
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
```
## Files likely touched
- `docs/public/sessions-and-review.md`
## Dependencies
None for wording; re-check the final UI label after Task 02 before marking this
task done.
## Parallelism
Parallel-safe with Task 01 because it owns only public documentation. Execution
still defaults to sequential without explicit user authorization.
## Inputs
- Spec `What` and unlink scenarios.
- Plan `Public Documentation` section.
- Existing multi-PR selector guidance in
`docs/public/sessions-and-review.md`.
## Risks
- Do not imply that unlinking closes the provider PR or disables GitHub
automation globally; only the selected task association leaves the task.
## Output contract
Report the exact wording location, files changed, validation results,
remaining risks/blockers, and update this task plus `plan.md` status in the same
conversation.