feat: unlink task pull requests (#2114)
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user