kandev/docs/decisions/2026-08-06-plugin-code-host-dashboard-parity.md

# ADR-2026-08-06-plugin-code-host-dashboard-parity: Code-Host Plugins Reuse Native Dashboard Primitives

**Status:** accepted
**Date:** 2026-08-06
**Area:** frontend, protocol

## Context

GitHub and GitLab dashboards share one interaction model, but their list and toolbar
components remained provider-coupled. The first Bitbucket plugin therefore reproduced
their appearance with plugin CSS while inventing a second dashboard review action and
an intermediate launch dialog. Visual similarity did not preserve the native task and
review workflow.

## Decision

Kandev owns provider-neutral code-host dashboard primitives under
`apps/web/components/integrations/` and exposes them through `host.ui`. GitHub, GitLab,
and compatible plugins render their result list, row, toolbar, scope controls, task
preset menu, linked-task indicator, and semantic change-request icons through those
same host components. Plugins select icon semantics such as open, merged, or closed;
they do not copy SVG paths from first-party providers.

Task presets use the same provider-neutral semantic icon keys as first-party presets.
The host resolves those keys to its Tabler components, so **Review**, **Address
feedback**, and **Fix CI** render the exact eye, message, and tool glyphs everywhere.
Plugins do not pass custom icon components or rely on a generic fallback when a native
semantic equivalent exists. Provider brand glyphs are different: the plugin owns that
component and Kandev reuses it across native surfaces.

Kandev also owns common task change-request linking anatomy. Code-host plugins invoke
the host task-link dialog contract with provider copy and a submit callback; they do not
rebuild the input, validation, loading state, footer, toast, close behavior, or responsive
surface inside an arbitrary plugin modal. A Link-submenu child names the target only
(for example, **Bitbucket Pull Request**) because the parent already supplies the verb.
The singleton plugin modal host mounts inside `AppShell`'s theme, tooltip, and toast
provider tree so host-owned workflows retain the same runtime contexts as first-party
dialogs.

Runtime React components remain in the Kandev host repository and are delivered by
the versioned `host.ui` contract. They do not move to a separate shared frontend
repository: host-owned React, Radix contexts, theme behavior, and release compatibility
must remain atomic. A future published SDK package may provide TypeScript contracts
and pure build-time helpers once multiple plugin repositories need them, but it must
not duplicate runtime UI implementations.

A code-host dashboard row is an inert result container. Its title opens the provider,
its metadata describes the change request, and its sole creation control is the compact
**Task** preset dropdown. Selecting a preset opens the host's real
`TaskCreateDialog` directly; provider linking runs after successful task creation.
Dashboard rows do not add a **Review** action or a provider-owned intermediate launch
modal. Review begins from linked task context through the existing review-provider
registry on desktop and mobile.

When the selected repository already exists in the workspace, the dialog keeps its
normal REST create transport. For a first-use plugin repository, the plugin may inject
the dialog's provider-neutral `createTask` transport and forward only native task
fields through an authenticated plugin action. The plugin server resolves the pull
request and trusted repository descriptor from its connection before calling Host
`Tasks.Create`; browser input never grants repository-provider authority. A per-dialog
launch identifier makes transport retries idempotent without limiting one pull request
to one task.

Kandev also owns task-scoped change-request status presentation. A review-provider
summary may include normalized status/check data; the host review registry preserves it,
refreshes it through the existing provider lifecycle, and automatically mounts the same
shared control in both first-party locations: the task topbar and the status row above
the chat composer (including passthrough sessions). The host owns the exact trigger,
delayed desktop hover popover, native mobile drawer, accessibility, touch geometry, and
responsive behavior. Providers do not register a visual status slot. They supply data,
refresh it around every 90 seconds, and retain provider API ownership.

The shared status body is the provider-neutral presentation extracted from GitHub's CI
popover. Its common header, grouped checks, review/comment summaries, links, loading,
empty, and error states render identically for built-ins and plugins. Provider-only
controls such as automation or merge actions are optional callbacks/capabilities inside
that anatomy, not alternate markup. Opening Review routes through the registered review
provider on desktop or the current mobile session.

Kandev likewise owns the common change-request detail presentation exposed through
`host.ui.ChangeRequestDetail`. GitHub and compatible review providers map their native
payloads into one normalized detail model and pass supported action callbacks. The host
owns header, branch/state metadata, description, reviews, checks, threaded comments,
action placement, loading/error states, scroll ownership, and responsive behavior.
Providers retain queries, authorization, mutation semantics, capability detection, and
normalization. A plugin may still own a review-panel adapter, but not a parallel visual
design for those common surfaces.

Every successful PR-from-task creation and watch-created task records the same durable
task-to-change-request association exposed by manual linking. Watch-owned links remain
authoritative in watch state and are unioned with manual link state when serving task
review/status and workspace association queries; implementations do not copy them into
a second store merely for presentation. Durable association, suppression, reservation,
and watch keys use provider ID, provider connection scope, immutable repository ID, and
change-request number. Repository paths, display keys, and clone URLs are mutable lookup
attributes and never durable identity. A changed connection epoch pauses an existing
watch before provider access; resuming explicitly rebinds it and discards its old cursor.

Task-scoped refresh also performs bounded branch-based discovery, equivalent to
GitHub's external-PR detection. It derives repository and checkout branch only from the
host-verified task, exact-matches an open provider change request's source branch, and
stores the result idempotently. Browser-supplied repository or branch values never
authorize automatic linking, and discovery failure does not hide an existing link.

The native task dialog's branch picker follows the same provider-neutral trust boundary.
For a persisted plugin-owned repository, the host resolves the active manifest owner and
invokes its declared workspace-scoped `repositories.branches` action with a descriptor
derived only from the stored repository row. The action returns normalized branch names;
the browser cannot substitute provider identity, host, namespace, clone URL, or repository
ID. GitHub remains on its first-party service path, while future code-host plugins reuse
this action instead of adding another host-native provider branch.

Provider adapters continue to own API queries, normalization, authorization, task-link
storage, provider data, and capability handling. Shared host components own presentation
and interaction geometry; they accept normalized data and callbacks and contain no
GitHub, GitLab, or Bitbucket API logic.

Repository discovery is a provider-neutral, server-searchable paged contract. The host
passes optional `query`, opaque `cursor`, and requested `limit` fields; providers return
either the legacy repository array or `{ repositories, nextCursor }`. The host follows
pages, rejects repeated cursors, and always binds returned provider identities to the
manifest owner. Registered plugin-owned provider icons are used in native repository
controls rather than a generic branch glyph. These rules keep large installations usable without adding
provider-specific search or pagination branches to Kandev. Provider cursors are bound to
the original query, state, provider connection scope, and immutable repository identity;
using one after any of those inputs changes fails before a provider request.

Task indicator and CI refreshes are summary operations. They fetch only normalized
change-request metadata, reviews, checks, and an inexpensive accurate unresolved-comment
count when the provider exposes one. Files, diffs, commits, and comment bodies load lazily
when Review opens. Both summary and detail responses remain bounded, with explicit
truncation instead of exceeding the authenticated plugin action response limit.

Pipeline/build status is read from the pull request's source (head) commit. The
destination commit describes the merge target and cannot represent the CI result for
the proposed change.

## Consequences

Code-host plugins require a host release containing these additive `host.ui` exports.
Dashboard fixes now apply uniformly to first-party and plugin providers, including
themes, touch targets, dropdown behavior, loading/error states, and row density.
Provider adapters remain independently releasable, while common review/status visuals
enter the versioned host contract. New semantic icon or presentation needs require an
additive host contract release rather than a plugin-local visual approximation. Plugin
repositories avoid a second runtime UI dependency and its version-skew/release-
coordination cost. Task-link, status, and detail fixes land once in the host and remain
consistent for first-party and plugin providers, without moving provider polling,
credentials, or API payloads into Kandev.

## Alternatives Considered

- Keep copying GitHub/GitLab markup and CSS into each plugin. Rejected because the
  first live implementation already drifted in behavior despite similar styling.
- Export GitHub's `PRList` directly. Rejected because its status hooks, payloads, and
  task associations are GitHub-specific rather than a reusable plugin contract.
- Permit each provider to choose its own dashboard actions. Rejected for first-party-
  parity code hosts because it makes task creation and review placement inconsistent.
- Put shared React components in a dedicated repository/package. Rejected because it
  would split host UI contexts and versioning; only pure types/helpers may be published
  later if repeated plugin-authoring demand justifies them.