feat(plugins): add source-control extension contracts (#2117)
@@ -26,11 +26,20 @@ reliably from database metadata alone. They become eligible for host-sensitive
|
||||
actions only after local-origin discovery or an explicit provider import/update
|
||||
records the host.
|
||||
|
||||
For plugin providers, authority alone is still insufficient: two self-managed
|
||||
instances can share one host while using different context roots. Persist an opaque,
|
||||
credential-free `provider_scope` alongside the provider's immutable repository ID.
|
||||
When both are present, the authoritative identity is workspace + provider + scope +
|
||||
repository ID; owner/name/clone URL are mutable routing and display data. Scoped
|
||||
imports never adopt an unscoped legacy row, and managed clone paths hash the complete
|
||||
scope and immutable ID. Before reusing an existing scoped checkout, Kandev verifies
|
||||
that its exact credential-free origin matches the requested clone URL.
|
||||
|
||||
## Consequences
|
||||
|
||||
Self-managed provider repositories are unambiguous across workspaces and host
|
||||
changes, and frontend selection can use the same identity contract as backend
|
||||
authorization. Repository persistence and API contracts gain one field, and
|
||||
Self-managed provider repositories are unambiguous across workspaces, hosts, and
|
||||
context roots, and frontend selection can use the same identity contract as backend
|
||||
authorization. Repository persistence and API contracts gain origin/scope fields, and
|
||||
legacy provider rows with unknown hosts require refresh or re-import before
|
||||
GitLab-specific linking and creation actions are available.
|
||||
|
||||
@@ -43,3 +52,5 @@ GitLab-specific linking and creation actions are available.
|
||||
existing repository as belonging to a different GitLab instance.
|
||||
- Keep host only in frontend state. Rejected because backend association and
|
||||
execution boundaries must enforce the same identity independently.
|
||||
- Treat authority plus owner/name as sufficient. Rejected because Data Center
|
||||
context roots can collide and repository slugs can be renamed.
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
# ADR-2026-07-31-authenticated-plugin-actions: Authenticated Plugin Actions
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-07-31
|
||||
**Area:** backend, frontend, protocol, security
|
||||
|
||||
## Context
|
||||
|
||||
The frontend plugin host currently maps plugin fetches toward `/api/plugins/:id/...`,
|
||||
while the host plugin endpoint is an externally callable webhook proxy. Reusing that
|
||||
public callback surface for browser commands would bypass normal user authentication,
|
||||
resource authorization, request limits, and cancellation controls.
|
||||
|
||||
Repository-provider plugins need browser-triggered connection, browse, review, and
|
||||
watch operations without turning each provider into a first-party HTTP route.
|
||||
|
||||
## Decision
|
||||
|
||||
The manifest declares plugin action keys, each with canonical field `scope` set to
|
||||
`workspace`, `task`, or `repository`, plus a bounded body size. Kandev continues to
|
||||
read the prerelease `resource_scope` spelling for package compatibility, but new
|
||||
manifests and serialized records use `scope`. Kandev exposes one authenticated
|
||||
route: `POST /api/plugins/:id/actions/:key`. It rejects inactive plugins and undeclared
|
||||
actions; normal Kandev authentication and server-side authorization verify every
|
||||
referenced resource before the host dispatches `Plugin.HandleAction`.
|
||||
|
||||
The host derives task/workspace relationships itself, forwards verified actor and
|
||||
resource context separately from untrusted action JSON, applies a hard timeout and
|
||||
cancellation, caps request/response bodies, and permits only a small response-header
|
||||
allowlist. The frontend contract is `host.api.invokeAction(...)`; plugin code must not
|
||||
use public webhook paths for authenticated browser work. Resource selectors use the
|
||||
documented camelCase JSON envelope (`workspaceId`, `taskId`, `repositoryId`). Callers
|
||||
may pass an `AbortSignal`; registry/provider teardown propagates it through the browser
|
||||
request and backend context.
|
||||
|
||||
`PluginActionResponse.status` is an optional HTTP status projection. Zero keeps the
|
||||
legacy `200 OK`; otherwise the host accepts statuses from 200 through 599. This lets
|
||||
provider-neutral adapters preserve safe domain outcomes such as invalid input,
|
||||
authentication expiry, conflicts, and rate limits without turning them into transport
|
||||
failures. `Retry-After` joins the response-header allowlist for throttling responses.
|
||||
Invalid statuses fail closed as `502`, while plugin transport/runtime failures remain
|
||||
`503` and do not expose internal error text.
|
||||
|
||||
The Go SDK defines stable typed action categories (`ActionErrorCode`) and shared HTTP
|
||||
projection (`ActionErrorHTTPStatus`). Plugins preserve causes with
|
||||
`CategorizeActionError`/`CategorizeActionErrorWithRetry` and map only typed provider or
|
||||
domain failures. Message-substring classification is outside the contract because it
|
||||
changes under wrapping/localization and can misreport authorization, conflict, or
|
||||
retry behavior.
|
||||
|
||||
`/api/plugins/:id/webhooks/:key` remains public only for provider callbacks/events.
|
||||
OAuth callbacks use signed, expiring, single-use state and PKCE.
|
||||
|
||||
## Consequences
|
||||
|
||||
Future plugins gain one reusable browser-to-plugin RPC seam without Kandev learning
|
||||
provider endpoints or payloads. Plugin authors declare each action up front and must
|
||||
design against explicit resource scope and bounded input/output. The host gains a
|
||||
security-critical authorization boundary, but no provider-specific handler branch.
|
||||
Callers can distinguish retryable and user-correctable domain outcomes while the host
|
||||
continues to redact unexpected implementation failures.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Reuse public webhook proxy for browser calls: rejected because callback endpoints do
|
||||
not establish user identity or authorize Kandev resources.
|
||||
- Add provider-specific REST routes in the host: rejected because every connector
|
||||
would pull provider payloads and authentication into core.
|
||||
- Let frontend bundles call plugin processes directly: rejected because managed plugin
|
||||
transport is not a browser-accessible authorization boundary.
|
||||
@@ -0,0 +1,81 @@
|
||||
# ADR-2026-07-31-plugin-repository-provider-extensions: Plugin Repository Provider Extensions
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-07-31
|
||||
**Area:** frontend, backend, protocol
|
||||
|
||||
## Context
|
||||
|
||||
Kandev task creation, Link menus, and review panels contain provider-specific GitHub/
|
||||
GitLab assumptions. A connector plugin must contribute repository discovery, pull-
|
||||
request actions, and native review UI without adding a Bitbucket branch or leaving
|
||||
mobile as a compressed desktop-only escape hatch.
|
||||
|
||||
## Decision
|
||||
|
||||
The frontend plugin registry gains revocable, manifest-owned registrations for:
|
||||
|
||||
- `registerRepositoryProvider(...)` with repository listing, URL matching, branch
|
||||
listing, and credential-free `inspectURL` descriptors whose clone URL is HTTPS;
|
||||
- `registerTaskAction(...)` for children of the existing **Link** submenu, with
|
||||
visibility and an async handler receiving read-only current
|
||||
workspace/task/repository context;
|
||||
- `registerReviewProvider(...)` with normalized task-item summaries, external-store
|
||||
`getSnapshot`/`subscribe`/cancellable `refresh`, and a plugin-owned `ReviewPanel`.
|
||||
|
||||
The frontend author boundary is the independently consumable, runtime-free
|
||||
`@kandev/plugin-sdk` package. It exposes named provider/review/UI contracts and a
|
||||
typed `host.context` read service. Private Zustand `AppState` access remains only as
|
||||
legacy runtime compatibility and is not part of the public SDK; official and new
|
||||
plugins must request provider-neutral context additions instead of copying host store
|
||||
shapes.
|
||||
|
||||
Registration icon fields accept either a backwards-compatible curated host icon
|
||||
name or a plugin-owned component rendered through the supplied host React runtime.
|
||||
Provider brand glyphs belong to the provider plugin, so adding another code host
|
||||
does not require a brand import or lookup-table edit in Kandev production code.
|
||||
|
||||
Repository URL ownership is established by cancellable, workspace-scoped structured
|
||||
inspection. `matchesURL` is optional and only narrows candidates; `inspectURL` returns
|
||||
`null` when the configured provider does not own the URL. The host rejects multiple
|
||||
successful inspectors as ambiguous rather than selecting registration order. This is
|
||||
required for overlapping self-hosted URL shapes.
|
||||
|
||||
Providers have unique active ownership, are removed on plugin disable/unload, and
|
||||
abort their in-flight work. Activation is transactional: a failed or timed-out
|
||||
`initialize` revokes partial registrations and fences late callbacks from restoring
|
||||
them. The host adapts GitHub, GitLab, and Azure implementations to the same contracts.
|
||||
It accepts a complete plugin-inspected provider descriptor, including an exact
|
||||
credential-free HTTPS clone URL, rather than parsing plugin provider URLs.
|
||||
|
||||
Task link actions render in existing desktop and visible mobile menus. A generic
|
||||
top-level `action` placement is deliberately deferred until Kandev has a host-owned
|
||||
workflow contract for command eligibility, result handling, and review navigation;
|
||||
accepting registrations with no consumer would be a false public API. Review panels use
|
||||
provider-neutral IDs and params `{ providerId, reviewKey }`; legacy GitHub/GitLab
|
||||
layout names remain aliases. The host's native desktop and mobile review surfaces own
|
||||
navigation and placement, while the plugin owns provider data and rendering.
|
||||
Task-link surfaces remain host-owned through `openTaskLinkDialog`; `openModal` remains
|
||||
available for plugin-owned workflows but is not a substitute for native task actions.
|
||||
Native review surfaces expose provider-neutral selection when
|
||||
multiple built-in or plugin reviews exist instead of silently choosing the first.
|
||||
Selections are revalidated by provider and review key after unload/reload, so a stale
|
||||
same-ID provider instance cannot keep an obsolete item selected.
|
||||
|
||||
## Consequences
|
||||
|
||||
Repository providers and review actions become extensible without host provider
|
||||
knowledge. Registry lifecycle and normalized item contracts are more deliberate, and
|
||||
existing built-ins require adapter work. Plugin review components must tolerate host
|
||||
selection, persistence, task switching, close, and mobile presentation changes.
|
||||
Released frontend plugins compile against a semver contract instead of the host
|
||||
application's private module graph.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Hard-code Bitbucket alongside GitHub/GitLab: rejected because every new provider
|
||||
would enlarge host provider unions and duplicate routing logic.
|
||||
- Give plugins only a standalone route: rejected because it omits native Link and
|
||||
review flows users already rely on.
|
||||
- Register React hooks for reviews: rejected because plugin load/unload can violate
|
||||
hook ordering; an external-store source is lifecycle-safe.
|
||||
@@ -0,0 +1,71 @@
|
||||
# ADR-2026-07-31-provider-neutral-git-credential-broker: Provider-Neutral Git Credential Broker
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-07-31
|
||||
**Area:** backend, protocol, security
|
||||
|
||||
## Context
|
||||
|
||||
GitHub has lease mechanics in a GitHub-specific broker, while other paths inject raw
|
||||
credentials into executor wiring. A repository-provider plugin needs clone, fetch, and
|
||||
push credentials without persisting tokens in URLs, task state, environment variables,
|
||||
logs, or process arguments. Self-managed repository URLs must retain exact host, path,
|
||||
and context path.
|
||||
|
||||
## Decision
|
||||
|
||||
Kandev extracts generic lease issuance, redemption, authorization, expiry, and
|
||||
revocation into `internal/gitcredentials/`. A composite resolver preserves current
|
||||
GitHub behavior through an adapter and adds an optional plugin `ResolveGitCredential`
|
||||
RPC. The plugin receives host-verified plugin/provider/workspace/task/session/
|
||||
repository/exact-host/path scope and returns a generic short-lived credential shape;
|
||||
provider-specific username/token formatting remains plugin-owned.
|
||||
|
||||
Credential-capable plugins also implement `GetGitCredentialBinding` for the same exact
|
||||
scope. It returns an opaque non-secret connection generation. Kandev stores that value
|
||||
when issuing a lease and compares it before and after each secret redemption; an empty,
|
||||
unsupported, rotated, or disconnected binding revokes the lease. The host never
|
||||
resolves a secret merely to inspect its generation.
|
||||
|
||||
Executors receive opaque short-lived helper leases. Redeeming a lease re-resolves
|
||||
against the live provider, so OAuth refresh does not require a task restart. Leases are
|
||||
scoped to exact workspace, task, session, repository, host, and path; they revoke on
|
||||
teardown, plugin disable/error/uninstall, credential-generation change, and connection
|
||||
reset. Disabling, failing, or uninstalling a plugin immediately revokes every lease for
|
||||
each provider it declared; later redemption does not wait for expiry. Host matching is
|
||||
normalized, while repository paths remain case-sensitive and exact. The helper carries
|
||||
the requested path without appending or removing `.git`. Remote executor transport uses
|
||||
HTTPS.
|
||||
|
||||
Host-local initial repository materialization uses the same verified scope before it
|
||||
creates a checkout. The orchestrator and workspace-source materializer must carry the
|
||||
canonical task ID, active session ID, and persisted repository ID explicitly into the
|
||||
clone credential request; the cloner must not reconstruct them from provider data or
|
||||
accept browser-selected identifiers. A plugin-provider clone without that complete
|
||||
scope fails closed. GitHub's legacy workspace credential adapter remains compatible,
|
||||
but generic plugin providers never receive a weaker initial-clone request than later
|
||||
fetch/push lease redemption.
|
||||
`RepositoryCloneURL` remains authoritative and is never reconstructed from provider
|
||||
fragments.
|
||||
|
||||
Before creating a worktree from an existing plugin-provider checkout, the orchestrator
|
||||
performs a strict origin refresh through that same exact scope. It then marks the
|
||||
in-memory launch as already refreshed; local and worktree preparers consume local and
|
||||
`origin/*` refs without issuing a second unauthenticated fetch or pull. A failed scoped
|
||||
refresh fails the launch closed.
|
||||
|
||||
## Consequences
|
||||
|
||||
New repository providers can participate in Git operations without host credential
|
||||
branches or secret leakage. The host must carry stricter lease scope and lifecycle
|
||||
checks, and plugins must resolve credentials promptly while handling rotation. GitLab
|
||||
is not migrated as part of this decision.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Put provider tokens in clone URLs or executor environment variables: rejected
|
||||
because both spread durable or observable secrets.
|
||||
- Add a Bitbucket broker beside GitHub's: rejected because it repeats a cross-provider
|
||||
security boundary.
|
||||
- Reconstruct clone URLs from provider fields: rejected because Data Center context
|
||||
paths and configured origins would be lost or silently changed.
|
||||
@@ -0,0 +1,54 @@
|
||||
# ADR-2026-08-01-bitbucket-initial-release-remains-unsigned: Bitbucket Initial Release Remains Unsigned
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-08-01
|
||||
**Area:** infra, workflow, security
|
||||
|
||||
## Context
|
||||
|
||||
Kandev currently verifies every plugin package's generated internal
|
||||
`checksums.txt`, but it does not verify `checksums.txt.sig`; installed packages
|
||||
are therefore reported as unsigned. The Bitbucket implementation plan had made
|
||||
a signed release a publication gate even though no host trust policy, verifier,
|
||||
approved key, or key-rotation process exists. Producing a signature that the
|
||||
host cannot authenticate would add ceremony without adding enforceable trust.
|
||||
|
||||
## Decision
|
||||
|
||||
The initial official `kandev-plugin-bitbucket` release may use the current
|
||||
unsigned marketplace contract. Its package must contain the generated internal
|
||||
`checksums.txt`, its public GitHub Release may include the standard advisory
|
||||
release-level checksum asset, and its source remains public and subject to the
|
||||
official catalog's maintainer review. Kandev will report the installed package
|
||||
as unsigned, and neither repository may claim that the release is signed or
|
||||
that its publisher provenance is cryptographically verified.
|
||||
|
||||
Signing is not a Bitbucket release gate. Enforceable plugin signing remains
|
||||
future host-wide work and requires a superseding decision covering signature
|
||||
verification, trusted-key or identity distribution, rotation and revocation,
|
||||
and fail-closed policy before official plugins can rely on it.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Bitbucket follows the trust posture already implemented for other plugins
|
||||
instead of inventing an integration-specific signing ceremony.
|
||||
- Package checksums detect extraction corruption and unexpected file changes,
|
||||
but they do not authenticate who produced an archive. Trust still rests on
|
||||
the public source and release repository, curated catalog review, and the
|
||||
operator's explicit install/update action.
|
||||
- The signing decision no longer blocks Bitbucket publication; host
|
||||
compatibility, live provider behavior, packaged-host, and credential-broker
|
||||
evidence remain independent release gates.
|
||||
- A future signing rollout must deliberately supersede this decision and may
|
||||
require republishing or reattesting the plugin.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- **Block Bitbucket until signing exists.** Rejected because no shipped verifier
|
||||
or trust-root policy exists, while the marketplace explicitly supports
|
||||
unsigned packages.
|
||||
- **Generate an ad hoc Ed25519 signature for Bitbucket.** Rejected because the
|
||||
host could not authenticate it and no approved distribution, rotation, or
|
||||
revocation process exists.
|
||||
- **Require Sigstore provenance for this plugin alone.** Rejected as a useful
|
||||
future direction that first needs a host-wide verification and policy design.
|
||||
@@ -33,6 +33,15 @@ timer:
|
||||
- stale generations cannot publish lifecycle completion or registrations over a newer
|
||||
load.
|
||||
|
||||
Repository and review provider callbacks use the same authority. The registry does not
|
||||
only request cooperative cancellation: it races every callback against the owning
|
||||
generation's abort signal, refuses to start already-aborted work, and rejects late
|
||||
results with `AbortError` even when third-party code ignores its signal. Subscription
|
||||
cleanup is likewise owner-tracked and idempotent. Unloaded code therefore cannot
|
||||
publish stale repositories, review snapshots, or callback results into a newer UI.
|
||||
Synchronous coarse callbacks such as repository `matchesURL` are also fault-isolated:
|
||||
a throw is treated as no match in every host call site, never as a task-dialog crash.
|
||||
|
||||
Desktop dockview and the phone task layout consume the same lifecycle authority. If a
|
||||
removed plugin panel is focused on a phone, the mobile session state changes to `chat`.
|
||||
Mobile-enabled registrations are exposed through one touch-sized **Panels** bottom-nav
|
||||
@@ -65,6 +74,10 @@ uninstall failures instead of warnings, so an operator may need to retry after a
|
||||
database problem; this is preferable to reporting success while retaining private
|
||||
data.
|
||||
|
||||
Provider work becomes result-fenced as well as cancellation-aware. This adds a small
|
||||
host wrapper around callbacks, but makes unload safety independent of third-party abort
|
||||
discipline.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- **Keep a longer revocation timeout.** Rejected because no finite duration proves that
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# ADR-2026-08-05-plugin-native-integration-settings: Plugins Contribute Native Integration Settings
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-08-05
|
||||
**Area:** frontend, protocol
|
||||
|
||||
## Context
|
||||
|
||||
An integration plugin can register an arbitrary plugin settings route, but that route
|
||||
appears under Settings > Plugins and does not participate in Kandev's native
|
||||
Settings > Integrations index, workspace navigation, or workspace-scoped URL model.
|
||||
Official integrations such as Bitbucket should use the same discovery and settings
|
||||
structure as built-in integrations without adding provider-specific rendering branches
|
||||
to the host.
|
||||
|
||||
## Decision
|
||||
|
||||
The frontend plugin registry adds
|
||||
`registerIntegrationSettings({ id, label, description, icon?, Component })`.
|
||||
`Component` receives `{ workspaceId?: string }`; the host renders it in the existing
|
||||
settings shell at both `/settings/integrations/{id}` and
|
||||
`/settings/workspace/{workspaceId}/integrations/{id}`, and adds the contribution to
|
||||
the native integrations index and workspace settings navigation. The host wraps the
|
||||
component's plugin-owned cards and controls in the shared `SettingsSection`, using the
|
||||
registered label, description, and resolved icon, and uses the label in settings
|
||||
topbar chrome.
|
||||
|
||||
Integration IDs are URL-safe slugs. First-party integration IDs remain reserved, one
|
||||
active plugin owns each contributed ID, collisions fail without replacing the current
|
||||
owner, and unload revokes the contribution. Labels, descriptions, icons, and rendering
|
||||
stay plugin-owned; the host contains no provider-specific settings branch. Curated
|
||||
brand icons remain a host-owned string-to-component map, including `bitbucket`.
|
||||
|
||||
Operational plugin routes remain separate. An integration's queue, review, or browse
|
||||
workbench may live at its normal plugin route, while credentials, connection health,
|
||||
and watch configuration use the native integration settings contribution.
|
||||
|
||||
## Consequences
|
||||
|
||||
Official and third-party integrations can feel first-party in Settings while retaining
|
||||
independent release ownership. Plugins must choose a stable non-reserved slug and make
|
||||
their settings component work with either an explicit workspace or the legacy global
|
||||
route; it returns the section body rather than duplicating the host heading. The host
|
||||
owns navigation, responsive settings chrome, error containment, and
|
||||
lifecycle; the plugin owns all provider-specific fields and behavior.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Keep integration configuration under Settings > Plugins: rejected because it makes
|
||||
an installed integration use a different information architecture from built-ins.
|
||||
- Let plugins register arbitrary `/settings/integrations/...` routes: rejected because
|
||||
route registration alone cannot safely contribute index metadata, workspace
|
||||
navigation, ownership, or collision handling.
|
||||
- Add a Bitbucket-specific settings page to the host: rejected because future provider
|
||||
plugins would repeat the same core coupling.
|
||||
@@ -0,0 +1,161 @@
|
||||
# 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.
|
||||
@@ -1,7 +1,7 @@
|
||||
# ADR-2026-08-10-no-em-dash-public-copy: Keep Em Dashes Out of Public Copy
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-08-10
|
||||
**Status:** accepted
|
||||
**Date:** 2026-08-10
|
||||
**Area:** frontend, infra
|
||||
|
||||
## Context
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# ADR-2026-08-10-plugin-change-request-mutations: Route Native Change-Request Mutations Through Providers
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-08-10
|
||||
**Area:** frontend, protocol
|
||||
|
||||
## Context
|
||||
|
||||
Repository-provider plugins can list repositories and expose review data, but Kandev's
|
||||
native **Create PR** workflow still delegates the complete operation to `agentctl`,
|
||||
whose provider-specific creation code supports only built-in hosts. Registered review
|
||||
providers likewise have no native unlink mutation or workspace association source, so
|
||||
plugin links cannot drive the same task-row indicators and unlink controls as built-in
|
||||
change requests.
|
||||
|
||||
## Decision
|
||||
|
||||
`RepositoryProviderRegistration` gains an optional provider-neutral change-request
|
||||
creation callback. Kandev keeps the native create dialog and performs the ordinary Git
|
||||
push first through the existing executor path. Only after that push succeeds does the
|
||||
host call the active repository provider with the current workspace, task, session,
|
||||
persisted repository, title, description, destination branch, and supported options.
|
||||
Plugin callbacks must cross the authenticated action boundary. The callback forwards
|
||||
the session only as a selector: Kandev verifies that it belongs to the task, resolves
|
||||
the selected repository's exact worktree branch server-side, and adds that branch to
|
||||
`VerifiedActionContext`. Plugin servers use this verified head branch and repository;
|
||||
browser body fields never select the source branch.
|
||||
Normalized open reviews from registered providers also participate in the native VCS
|
||||
action state, so an already-linked plugin change request suppresses the primary
|
||||
**Create PR** action exactly like a built-in pull request.
|
||||
For a task-scoped action, the browser may include optional `repositoryId` and
|
||||
`sessionId` selectors. Kandev accepts the repository only when it is attached to the
|
||||
verified task and accepts the session only when it belongs to that task. When both
|
||||
selectors are present, the repository must have a worktree in that session and Kandev
|
||||
supplies its non-empty branch as `headBranch`; omitting selectors preserves existing
|
||||
task-only action behavior.
|
||||
|
||||
`ReviewProviderRegistration` gains optional unlink and workspace-association external-
|
||||
store methods. Kandev renders unlink controls and task-row/card change-request glyphs
|
||||
from those normalized callbacks and snapshots. Providers own association queries and
|
||||
mutations; the host owns placement, accessibility, responsive behavior, pending/error
|
||||
feedback, lifecycle cancellation, and semantic icons.
|
||||
An explicit unlink must remain detached: provider implementations suppress automatic
|
||||
source-branch relinking for that task/review pair until the user explicitly links it
|
||||
again, and watch-owned associations relinquish ownership without deleting the task.
|
||||
|
||||
Built-in providers retain their current adapters. `agentctl` receives no Bitbucket or
|
||||
plugin dispatch branch. Callback work and association subscriptions are revoked with
|
||||
their owning plugin, matching the existing repository/review provider lifecycle.
|
||||
|
||||
## Consequences
|
||||
|
||||
Future code-host plugins can participate in native create, unlink, and task-indicator
|
||||
workflows without provider-specific host branches. Creation now has a deliberate
|
||||
two-stage failure model: a successful push followed by a failed remote create reopens
|
||||
the native dialog in retry state and does not push again unnecessarily. Provider
|
||||
implementations must truthfully declare option support and make create retries safe.
|
||||
Normal Kandev tasks need not copy session worktree branches into task-repository
|
||||
metadata merely to authorize a plugin create operation.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Add Bitbucket creation to `agentctl`: rejected because it moves plugin API/auth logic
|
||||
into the host and repeats for every future provider.
|
||||
- Register a plugin-owned **Create PR** button or modal: rejected because it duplicates
|
||||
Kandev's native Git eligibility, dialog, feedback, and mobile behavior.
|
||||
- Infer plugin links by refreshing every task's full review detail: rejected because a
|
||||
task list would create an unbounded provider-request fan-out; one workspace
|
||||
association snapshot is the reusable bounded contract.
|
||||
@@ -0,0 +1,43 @@
|
||||
# ADR-2026-08-12-plugin-localization-contract: Host-Scoped Plugin Localization
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-08-12
|
||||
**Area:** frontend, protocol
|
||||
|
||||
## Context
|
||||
|
||||
Native UI plugins render inside Kandev but ship independently, so their copy cannot live in the
|
||||
application's built-in catalogs. Giving plugins direct access to the shared i18next instance would
|
||||
let one plugin collide with or remove another plugin's messages, and hardcoded English prevents
|
||||
locale changes and pseudo-locale QA.
|
||||
|
||||
## Decision
|
||||
|
||||
The runtime-free `@kandev/plugin-sdk` contract exposes
|
||||
`registry.registerTranslations(catalogs)` plus a plugin-scoped `host.i18n` API. Every catalog must
|
||||
include English, may target only Kandev-supported locales, and uses bounded flat message keys. The
|
||||
host mounts catalogs under a namespace derived from the verified plugin ID, supplies imperative
|
||||
`t()` and reactive `useTranslation()` access, and removes resources on disable, reload, failed load,
|
||||
or uninstall.
|
||||
|
||||
Plugin React surfaces use `host.i18n.useTranslation()` so locale changes rerender without reload.
|
||||
Imperative callbacks use `host.i18n.t()` at execution time. Registration metadata that must remain
|
||||
live uses accessor properties backed by `host.i18n.t()`; the registry preserves those accessors and
|
||||
invalidates its subscribers when locale changes. Provider data, user content, identifiers, and
|
||||
machine-readable discriminants are never translated or used as translated control-flow tokens.
|
||||
|
||||
## Consequences
|
||||
|
||||
Official and third-party plugins can follow Kandev locale and pseudo-locale behavior without
|
||||
bundling i18next or importing private application modules. Catalogs remain isolated and lifecycle
|
||||
safe, while English remains a guaranteed fallback. Plugin authors must maintain their own catalogs,
|
||||
and human-locale parity remains advisory just like Kandev's built-in catalogs.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Put official plugin copy in Kandev's built-in catalogs. Rejected because plugin releases would
|
||||
remain coupled to host releases and community plugins could not participate.
|
||||
- Expose the shared i18next instance. Rejected because namespace ownership and cleanup would be
|
||||
unenforceable.
|
||||
- Let each plugin bundle its own localization runtime. Rejected because locale selection, fallback,
|
||||
pseudo-locale QA, and lifecycle behavior would diverge across plugins.
|
||||
@@ -64,6 +64,10 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
|
||||
| 2026-07-23-post-commit-hook-aware-verification | [Post-Commit Hook-Aware Verification](2026-07-23-post-commit-hook-aware-verification.md) | superseded by 2026-07-26 | workflow | 2026-07-23 |
|
||||
| 2026-07-23-workspace-source-root-move-boundary | [Workspace Source Root Move Boundary](2026-07-23-workspace-source-root-move-boundary.md) | accepted | backend | 2026-07-23 |
|
||||
| 2026-07-24-operator-owned-agent-launcher-settings | [Operator-Owned Agent Launcher Settings](2026-07-24-operator-owned-agent-launcher-settings.md) | accepted | backend, frontend, protocol | 2026-07-24 |
|
||||
| 2026-08-05-plugin-native-integration-settings | [Plugins Contribute Native Integration Settings](2026-08-05-plugin-native-integration-settings.md) | accepted | frontend, protocol | 2026-08-05 |
|
||||
| 2026-08-06-plugin-code-host-dashboard-parity | [Code-Host Plugins Reuse Native Dashboard Primitives](2026-08-06-plugin-code-host-dashboard-parity.md) | accepted | frontend, protocol | 2026-08-06 |
|
||||
| 2026-08-10-plugin-change-request-mutations | [Route Native Change-Request Mutations Through Providers](2026-08-10-plugin-change-request-mutations.md) | accepted | frontend, protocol | 2026-08-10 |
|
||||
| 2026-08-12-plugin-localization-contract | [Host-Scoped Plugin Localization](2026-08-12-plugin-localization-contract.md) | accepted | frontend, protocol | 2026-08-12 |
|
||||
| 2026-07-18-turn-configuration-snapshots | [Attribute runtime configuration to turns](2026-07-18-turn-configuration-snapshots.md) | accepted | backend, frontend | 2026-07-18 |
|
||||
| 2026-07-22-gpg-signed-release-tags | [GPG-signed release tags](2026-07-22-gpg-signed-release-tags.md) | accepted | infra, workflow | 2026-07-22 |
|
||||
| 2026-07-19-reject-mcp-actions-on-raw-websocket | [Reject MCP Actions on the Raw WebSocket](2026-07-19-reject-mcp-actions-on-raw-websocket.md) | accepted | backend, protocol | 2026-07-19 |
|
||||
@@ -93,6 +97,10 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
|
||||
| 2026-07-30-session-owned-mcp-observability | [Keep MCP Attachment Evidence Session Owned](2026-07-30-session-owned-mcp-observability.md) | accepted | backend, frontend, protocol, security | 2026-07-30 |
|
||||
| 2026-07-30-file-backed-diagnostic-bundles | [File-backed diagnostic bundles](2026-07-30-file-backed-diagnostic-bundles.md) | accepted | backend, frontend, infra, protocol, workflow | 2026-07-30 |
|
||||
| 2026-07-30-runtime-task-state-before-running-event | [Publish Task State Before Running Session State](2026-07-30-runtime-task-state-before-running-event.md) | accepted | backend, frontend, protocol, workflow | 2026-07-30 |
|
||||
| 2026-07-31-authenticated-plugin-actions | [Authenticated Plugin Actions](2026-07-31-authenticated-plugin-actions.md) | accepted | backend, frontend, protocol, security | 2026-07-31 |
|
||||
| 2026-07-31-plugin-repository-provider-extensions | [Plugin Repository Provider Extensions](2026-07-31-plugin-repository-provider-extensions.md) | accepted | frontend, backend, protocol | 2026-07-31 |
|
||||
| 2026-07-31-provider-neutral-git-credential-broker | [Provider-Neutral Git Credential Broker](2026-07-31-provider-neutral-git-credential-broker.md) | accepted | backend, protocol, security | 2026-07-31 |
|
||||
| 2026-08-01-bitbucket-initial-release-remains-unsigned | [Bitbucket Initial Release Remains Unsigned](2026-08-01-bitbucket-initial-release-remains-unsigned.md) | accepted | infra, workflow, security | 2026-08-01 |
|
||||
| 2026-07-31-npm-nightly-release-channel | [Publish deterministic npm-only nightlies](2026-07-31-npm-nightly-release-channel.md) | accepted (amended 2026-08-03) | workflow, backend, frontend, cli | 2026-07-31 |
|
||||
| 2026-07-31-isolate-manual-pr-review-content | [Isolate Manual PR Review Content](2026-07-31-isolate-manual-pr-review-content.md) | accepted | infra, workflow, security | 2026-07-31 |
|
||||
| 2026-07-31-agent-generated-task-titles | [Bind Agent Title Generation to Pending Tasks](2026-07-31-agent-generated-task-titles.md) | accepted | backend, frontend, protocol | 2026-07-31 |
|
||||
|
||||
@@ -0,0 +1,208 @@
|
||||
---
|
||||
spec: docs/specs/bitbucket-plugin/spec.md
|
||||
created: 2026-07-31
|
||||
status: in_progress
|
||||
---
|
||||
|
||||
# Implementation Plan: Bitbucket Connector Plugin
|
||||
|
||||
## Overview
|
||||
|
||||
Release generic host seams before plugin behavior: authenticated actions, plugin
|
||||
registry contracts, dynamic composer sources, richer task ownership, and a provider-
|
||||
neutral credential broker. Build Cloud/Data Center adapters and plugin workflows only
|
||||
after those seams land, then prove native task, review, composer, desktop, mobile, and
|
||||
credential behavior through cross-repository acceptance.
|
||||
|
||||
The host remains provider-neutral. `kdlbs/kandev-plugin-bitbucket` owns Bitbucket
|
||||
payloads, auth, product probes, watches, and UI. The required native hooks remain
|
||||
**Link → Bitbucket Pull Request**, host-rendered review/status surfaces supplied by
|
||||
plugin adapters, and composer `#` source search with submit-time authorization.
|
||||
|
||||
## Host contracts
|
||||
|
||||
- Add additive plugin RPC/SDK/manifest shapes and authenticated action dispatch.
|
||||
- Add revocable repository-provider, task-action, and review-provider frontend
|
||||
registrations; migrate built-ins through the same registry.
|
||||
- Register/unregister dynamic backend composer reference sources and reauthorize every
|
||||
reference at submission.
|
||||
- Extend plugin-owned task lifecycle and provider-neutral descriptor validation.
|
||||
- Replace GitHub-only broker mechanics with composite short-lived credential leases.
|
||||
|
||||
## Plugin repository
|
||||
|
||||
- Bootstrap `kdlbs/kandev-plugin-bitbucket` from official template in its attached
|
||||
Kandev workspace; do not nest a clone under this repository.
|
||||
- Implement separate Cloud and Data Center adapters, workspace-scoped encrypted auth,
|
||||
health, capabilities, task/link/Git/watch workflows, and native registrations.
|
||||
- Publish only after source/package, host/plugin desktop/mobile, and container broker
|
||||
acceptance pass; marketplace mutation is last.
|
||||
|
||||
## Tests
|
||||
|
||||
- Host protocol/action tests cover declaration, normal authentication, resource
|
||||
authorization, body caps, timeout/cancellation, response headers, and SDK
|
||||
compatibility.
|
||||
- Registry/task/review tests cover ownership collisions, unload cancellation, complete
|
||||
provider descriptors, Link-group actions, layout aliases, desktop/mobile review
|
||||
selection, and plugin teardown.
|
||||
- Composer tests cover dynamic source lifecycle, canonical identity, workspace
|
||||
isolation, search and submission authorization, disabled plugins, and generic
|
||||
presentation.
|
||||
- Credential tests cover exact scope, expiry/revocation, refreshed resolution,
|
||||
leakage, custom host/path, and local/remote executor helper use.
|
||||
- Plugin tests cover Cloud/DC fixture mapping, auth rotation/PKCE, capability probes,
|
||||
health/retry, watch concurrency/recovery, ownership-safe deletion, and responsive UI.
|
||||
- Plugin page parity tests compare `/bitbucket` with the first-party `/github`
|
||||
list-first structure: scope bar, compact toolbar, bordered rows, focused review URL,
|
||||
and native mobile list/detail navigation.
|
||||
|
||||
## E2E tests
|
||||
|
||||
- Install/enable fixture package; call a declared authenticated action without exposing
|
||||
a webhook as a browser RPC.
|
||||
- Select a plugin provider in native task creation, import/inspect a PR, invoke
|
||||
**Link → Bitbucket Pull Request**, then open the plugin native review panel on
|
||||
desktop and mobile.
|
||||
- Select a `#` Bitbucket pull request and prove submitted metadata is authorized.
|
||||
- Verify watch-created task, unload/reload cleanup, secret-free failure UI, and real
|
||||
HTTPS clone/push in the containers project.
|
||||
|
||||
## Implementation waves and task files
|
||||
|
||||
Wave 0 (parallel-safe, docs/external repository only):
|
||||
|
||||
- [x] [task 01 — design package](task-01-design-package.md)
|
||||
- [x] [task 02 — plugin repository bootstrap](task-02-plugin-repository-bootstrap.md)
|
||||
|
||||
Wave 1 (parallel-safe after task 01):
|
||||
|
||||
- [x] [task 03 — protocol, manifest, authenticated actions](task-03-protocol-manifest-actions.md)
|
||||
- [x] [task 04 — frontend plugin registry contracts](task-04-frontend-plugin-registry.md)
|
||||
|
||||
Wave 2 (parallel-safe after contract foundations):
|
||||
|
||||
- [x] [task 05 — dynamic composer reference sources](task-05-dynamic-composer-reference-sources.md)
|
||||
- [x] [task 06 — plugin-owned task lifecycle](task-06-plugin-owned-task-lifecycle.md)
|
||||
- [x] [task 07 — provider-neutral git credential broker](task-07-provider-neutral-git-credentials.md)
|
||||
- [x] [task 08 — native repository provider task creation](task-08-native-repository-provider.md)
|
||||
- [x] [task 09 — native Link and review surfaces](task-09-native-link-review-surfaces.md)
|
||||
|
||||
Wave 3 (plugin repository after declared dependencies):
|
||||
|
||||
- [x] [task 10 — Cloud/DC domain and authentication](task-10-cloud-dc-domain-auth.md)
|
||||
- [x] [task 11 — task, Git, linking, and watch workflows](task-11-plugin-workflows-watches.md)
|
||||
- [x] [task 12 — plugin UI and native registrations](task-12-plugin-ui-native-registrations.md)
|
||||
|
||||
Wave 3b (corrective UI pass after live evaluation):
|
||||
|
||||
- [x] [task 12b — GitHub-parity Bitbucket page](task-12b-github-parity-page.md)
|
||||
|
||||
Wave 3c (exact shared interaction parity after user evaluation):
|
||||
|
||||
- [x] [task 12c — exact shared code-host UI parity](task-12c-exact-code-host-ui-parity.md)
|
||||
|
||||
Wave 3d (native task-link parity after manual evaluation):
|
||||
|
||||
- [x] [task 12d — host-native task-link dialog parity](task-12d-host-native-task-link-parity.md)
|
||||
|
||||
Wave 3e (corrective host-owned task status after manual evaluation):
|
||||
|
||||
- [x] [task 12e — registry-backed shared task status](task-12e-shared-task-status.md)
|
||||
|
||||
Wave 3f (corrective host-owned review presentation; parallel with 12e):
|
||||
|
||||
- [x] [task 12f — shared change-request detail](task-12f-shared-review-detail.md)
|
||||
|
||||
Wave 3g (after 12e and 12f):
|
||||
|
||||
- [x] [task 12g — Bitbucket adapters and live parity acceptance](task-12g-bitbucket-status-detail-adapters.md)
|
||||
|
||||
Wave 3h (corrective native workflow pass after final manual evaluation):
|
||||
|
||||
- [x] [task 12h — native create, unlink, task indicators, and saved queries](task-12h-native-create-unlink-indicators-saved-queries.md)
|
||||
|
||||
Wave 3i (corrective sidebar hover parity after manual evaluation):
|
||||
|
||||
- [x] [task 12i — shared task-indicator hover summary](task-12i-shared-task-indicator-hover-summary.md)
|
||||
|
||||
Wave 4:
|
||||
|
||||
- [ ] [task 13 — contract E2E, release, and marketplace](task-13-contract-e2e-release-marketplace.md)
|
||||
|
||||
## Current status
|
||||
|
||||
Tasks 01–12i are implemented. Task 13 remains the
|
||||
release/marketplace gate.
|
||||
Live Cloud evaluation showed that task 12's permanent
|
||||
desktop queue/review split diverged from the first-party `/github` page despite being
|
||||
functionally complete; task 12b replaced it with the approved list-first parity model
|
||||
and passed the live Cloud-connected desktop/mobile suite. User evaluation then found
|
||||
that its equal **Task**/**Review** buttons and intermediate launch modal still diverged
|
||||
from GitHub/GitLab interaction behavior. Task 12c replaced copied presentation and
|
||||
plugin-specific launch/review placement with shared host primitives and native task
|
||||
creation. Its first pass passed the complete host suite (1,010 files / 7,712 tests) and
|
||||
seven live Cloud desktop/mobile checks. Manual testing then found that scope pills did
|
||||
not commit their filter into the visible query and plugin-drawn SVGs did not match the
|
||||
host's semantic icons. The corrected evaluation package commits scope selections
|
||||
into the visible query, uses host-owned semantic Tabler icons, and passes eight live
|
||||
Cloud desktop/mobile checks. It also registers the exact **Bitbucket Pull Request**
|
||||
submenu label and invokes the shared host task-link dialog. Live evaluation caught the
|
||||
modal host outside the host toast-provider tree; the corrected topology now mounts
|
||||
plugin modals inside `AppShell`, and a production-topology regression test protects the
|
||||
real form. Empty validation, authenticated Cloud linking, close-on-success, toast,
|
||||
desktop geometry, and mobile no-overflow behavior pass against the disposable account.
|
||||
Version 0.1.7 also proves exact preset glyphs, persisted-provider branch selection,
|
||||
manual linking, exact-branch auto-link recovery, restart-safe watch associations, native
|
||||
desktop/mobile Review, and live CI polling. The CI marker was changed
|
||||
`SUCCESSFUL -> INPROGRESS -> SUCCESSFUL`; each 90-second poll updated the shared host
|
||||
glyph and the remote fixture was restored.
|
||||
Manual evaluation then established that the topbar body and Review panel were still
|
||||
plugin-owned approximations and that no Bitbucket CI chip existed above the composer.
|
||||
Tasks 12e–12g replaced those approximations with registry-backed, host-owned surfaces
|
||||
used by GitHub itself. Package 0.1.10 passed desktop/touch live acceptance: the shared
|
||||
topbar/composer anatomy, shared review detail, manual linking, exact-branch auto-link,
|
||||
and a real `SUCCESSFUL -> INPROGRESS -> FAILED -> SUCCESSFUL` pipeline cycle all passed;
|
||||
the fixture was restored.
|
||||
Task 12h closed the final manual-evaluation gaps. Package 0.1.12 proved native Create PR
|
||||
through the registered provider after a real Git push, shared unlink with reload-safe
|
||||
detachment, workspace-hydrated sidebar indicators, and saved-query persistence and
|
||||
restoration. The native Create PR control remains Kandev's existing Changes-panel
|
||||
control; no duplicate plugin-specific create button was added.
|
||||
Task 12i removed the association indicator's count-only tooltip. Registered providers
|
||||
now reuse GitHub's host-owned structured pull-request summary and load task detail only
|
||||
when the desktop indicator opens; the existing mobile Status/Review surfaces remain the
|
||||
touch path. A manual follow-up also moved task-indicator color derivation into the shared
|
||||
provider-neutral status palette, so normalized pipeline/review state changes the glyph
|
||||
without provider CSS tokens. Unit, packaged-plugin desktop E2E, mobile contract E2E,
|
||||
typecheck, and lint pass. The public authoring reference now includes a code-host hook
|
||||
surface map and focused captures of the shared dashboard, repository picker, Link flow,
|
||||
task status, CI, Review, and composer reference search.
|
||||
The packaged generic host contract passes on desktop and
|
||||
mobile. The actual package passes its unconfigured action, disable/re-enable, desktop,
|
||||
and mobile lifecycle checks; its canonical composer reference now rehydrates the
|
||||
repository/PR identity and performs live submit-time authorization. Plugin unit, race,
|
||||
build, and five-platform archive checks pass. Cloud acceptance is complete for the
|
||||
available disposable target. Task 13 remains in progress until a disposable Data Center
|
||||
target and a container-reachable HTTPS credential-broker URL are available, the host
|
||||
changes ship
|
||||
in a release that can be named by `min_kandev_version`, and the remaining live gates
|
||||
pass. The initial plugin release intentionally follows the current checksum-verified,
|
||||
unsigned marketplace contract under
|
||||
[ADR-2026-08-01-bitbucket-initial-release-remains-unsigned](../../decisions/2026-08-01-bitbucket-initial-release-remains-unsigned.md);
|
||||
no signature or cryptographic publisher-provenance claim is made. No plugin tag,
|
||||
release, or marketplace entry is created before the other gates pass.
|
||||
|
||||
## Risks
|
||||
|
||||
- Full parity is complete only when every capability-matrix row passes; alpha sideloads
|
||||
may be partial but must be marked partial.
|
||||
- BYO OAuth registration and Data Center network/version variation require clear
|
||||
failure states, fixture coverage, and a release-time compatibility matrix.
|
||||
- Generic host seams must pass a second-provider test: Bitbucket types, URL parsing,
|
||||
and auth rules in host code are a design failure.
|
||||
- Cross-repository release ordering is strict: host contract release precedes plugin
|
||||
compatibility gate, package release, and marketplace entry.
|
||||
- Same-version development copies keep the plugin bundle URL stable. Live evaluation
|
||||
must use a fresh document or hard reload after UI-only asset replacement; released
|
||||
plugin updates change the manifest version and therefore the bundle URL.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
id: "01-design-package"
|
||||
title: "Design package and task files"
|
||||
status: completed
|
||||
wave: 0
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 01: Design package and task files
|
||||
|
||||
## Intent
|
||||
|
||||
Materialize approved Bitbucket connector behavior, generic host boundaries, ADRs, and
|
||||
dependency-scoped implementation packets without touching production code.
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `docs/specs/bitbucket-plugin/spec.md`
|
||||
- `docs/specs/INDEX.md`
|
||||
- `docs/specs/plugins/spec.md`
|
||||
- `docs/decisions/2026-07-31-authenticated-plugin-actions.md`
|
||||
- `docs/decisions/2026-07-31-plugin-repository-provider-extensions.md`
|
||||
- `docs/decisions/2026-07-31-provider-neutral-git-credential-broker.md`
|
||||
- `docs/decisions/INDEX.md`
|
||||
- `docs/plans/bitbucket-plugin/`
|
||||
- `docs/plans/plugins/GRPC-CONTRACT.md`
|
||||
- `docs/plans/plugins/PLUGIN-API.md`
|
||||
- `docs/plans/plugins/HOST-DATA-API.proto`
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Spec preserves Cloud+DC, API token/PAT+OAuth, full supported-capability parity,
|
||||
plugin-first boundaries, native Link/review hooks, and composer submission
|
||||
reauthorization.
|
||||
2. Three ADRs and frozen contracts define generic reusable seams without Bitbucket API
|
||||
payloads in the host.
|
||||
3. `task-01` through `task-13` declare dependencies, owned paths, acceptance, exact
|
||||
checks, and risks; indexes and relative links resolve.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
git diff --check
|
||||
rg -n 'Link → Bitbucket Pull Request|submit-time|reauthoriz|Cloud|Data Center' docs/specs/bitbucket-plugin docs/plans/bitbucket-plugin
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Frozen contract drift can make later host/plugin tasks incompatible. Reconcile every
|
||||
contract amendment with the approved parent plan before implementation starts.
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
id: "02-plugin-repository-bootstrap"
|
||||
title: "Dedicated plugin repository bootstrap"
|
||||
status: completed
|
||||
wave: 0
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 02: Dedicated plugin repository bootstrap
|
||||
|
||||
## Intent
|
||||
|
||||
Create public `kdlbs/kandev-plugin-bitbucket` from official plugin template and attach
|
||||
that repository to its Kandev task. Establish package/CI skeleton only; make no
|
||||
unsupported product claims.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- Attached `kdlbs/kandev-plugin-bitbucket` worktree only.
|
||||
- Template-owned manifest, package, CI, backend, and UI skeleton files in that
|
||||
repository.
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Repository is public, template-derived, and attached to the task rather than
|
||||
cloned inside this host worktree.
|
||||
2. Skeleton identifies `kandev-plugin-bitbucket`, ships no OAuth secret, and contains
|
||||
no claimed minimum host version before generic seams release.
|
||||
3. CI/package layout can build the release archive expected by task 13.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
make test
|
||||
make vet
|
||||
make build
|
||||
make package
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Template drift can invalidate guessed commands or archive layout. Use the template's
|
||||
current documented targets; do not add product behavior in this bootstrap task.
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
id: "03-protocol-manifest-actions"
|
||||
title: "Plugin protocol, manifest ownership, and authenticated actions"
|
||||
status: completed
|
||||
wave: 1
|
||||
depends_on: ["01-design-package"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 03: Plugin protocol, manifest ownership, and authenticated actions
|
||||
|
||||
## Intent
|
||||
|
||||
Add every additive RPC, SDK, manifest, and authenticated-action shape required by later
|
||||
task, reference, credential, and repository-provider work. No later task edits proto
|
||||
or generated stubs.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/backend/proto/kandev/plugin/v1/plugin.proto`
|
||||
- Generated `apps/backend/proto/kandev/plugin/v1/plugin.pb.go`
|
||||
- Generated `apps/backend/proto/kandev/plugin/v1/plugin_grpc.pb.go`
|
||||
- `apps/backend/pkg/pluginsdk/plugin.go`
|
||||
- `apps/backend/pkg/pluginsdk/serve.go`
|
||||
- `apps/backend/pkg/pluginsdk/data_types.go`
|
||||
- `apps/backend/pkg/pluginsdk/host.go`
|
||||
- `apps/backend/internal/plugins/manifest/manifest.go`
|
||||
- `apps/backend/internal/plugins/manifest/validate.go`
|
||||
- `apps/backend/internal/plugins/handlers.go`
|
||||
- `apps/backend/internal/backendapp/helpers.go`
|
||||
- `apps/backend/internal/backendapp/plugins_test.go`
|
||||
- `apps/backend/internal/webapp/payload.go`
|
||||
- `apps/backend/internal/plugins/runtime/testdata/fixtureplugin/main.go`
|
||||
- Focused sibling tests under `apps/backend/pkg/pluginsdk/` and
|
||||
`apps/backend/internal/plugins/{manifest/,handlers_test.go}`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 01.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Protocol exposes optional action, reference search/authorization, credential
|
||||
resolution, executor-profile read, and rich plugin-owned task lifecycle shapes;
|
||||
old plugins receive clear unsupported responses.
|
||||
2. Manifest validates declared actions, repository-provider ownership, and reference
|
||||
source ownership/collisions before dispatch.
|
||||
3. Active UI-plugin boot payload projects manifest `repository_providers` as optional
|
||||
JSON `repositoryProviderIds`, preserving an explicitly present empty declaration.
|
||||
4. Authenticated action handler rejects undeclared/unauthorized resources, bounds
|
||||
bodies, passes verified context apart from payload, honors cancellation/timeout, and
|
||||
allows only safe response headers.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps/backend && go test ./pkg/pluginsdk/... ./internal/plugins/... ./internal/plugins/manifest/...
|
||||
make -C apps/backend lint
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Generated protobuf changes are shared contract files. Keep additions wire-compatible;
|
||||
never hand-edit generated files or expose Bitbucket-specific fields.
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
id: "04-frontend-plugin-registry"
|
||||
title: "Frontend plugin registry contracts"
|
||||
status: completed
|
||||
wave: 1
|
||||
depends_on: ["01-design-package"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 04: Frontend plugin registry contracts
|
||||
|
||||
## Intent
|
||||
|
||||
Add generic revocable action, repository-provider, task-action, review-provider,
|
||||
integration-settings, Drawer, and responsive contracts to the frontend plugin host.
|
||||
Do not rewrite task-create or review screens in this task.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/web/lib/plugins/types.ts`
|
||||
- `apps/web/lib/plugins/registry.ts`
|
||||
- `apps/web/lib/plugins/host-api.ts`
|
||||
- `apps/web/lib/plugins/host.ts`
|
||||
- `apps/web/lib/plugins/active-plugin.ts`
|
||||
- `apps/web/src/boot-payload.ts`
|
||||
- `apps/web/lib/plugins/registry.test.ts`
|
||||
- `apps/web/lib/plugins/host-api.test.ts`
|
||||
- `apps/web/lib/plugins/host.test.ts`
|
||||
- `apps/web/lib/plugins/active-plugin.test.ts`
|
||||
- `apps/web/src/boot-payload.test.ts`
|
||||
- Built-in registration adapters directly required by those registry files.
|
||||
- Native settings integration index, route resolver, workspace navigation, icons, and tests.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 01.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. `host.api.invokeAction(...)` targets declared authenticated actions; repository,
|
||||
task-action, and review registrations are owner-scoped and revoke on disable.
|
||||
2. Duplicate provider ownership fails deterministically and unload aborts in-flight
|
||||
work; review items use external-store sources rather than plugin React hooks.
|
||||
3. `ActivePlugin.repositoryProviderIds?: string[]` parses JSON
|
||||
`repositoryProviderIds`; loader records present manifest declarations before
|
||||
`initialize`, uses them as repository/review provider ownership allowlist, and
|
||||
preserves absent-field compatibility for older payloads.
|
||||
4. Host exports Drawer family and supported responsive breakpoint behavior needed for
|
||||
native mobile plugin UI.
|
||||
5. `registerIntegrationSettings({ id, label, description, icon?, Component })`
|
||||
contributes lifecycle-safe native global/workspace settings pages, index cards, and
|
||||
workspace navigation without provider-specific host rendering.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps/web && pnpm test -- lib/plugins/registry.test.ts lib/plugins/host-api.test.ts lib/plugins/host.test.ts lib/plugins/active-plugin.test.ts src/boot-payload.test.ts
|
||||
cd apps/web && pnpm run typecheck
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Registry contracts become public plugin API. Avoid closed provider unions and avoid
|
||||
making a Bitbucket registration special.
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
id: "05-dynamic-composer-reference-sources"
|
||||
title: "Dynamic composer reference sources"
|
||||
status: completed
|
||||
wave: 2
|
||||
depends_on: ["01-design-package", "03-protocol-manifest-actions"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 05: Dynamic composer reference sources
|
||||
|
||||
## Intent
|
||||
|
||||
Bridge active manifest-declared plugin reference sources into the existing backend
|
||||
mentions registry, preserving host canonicalization and live authorization at search
|
||||
and submission.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/backend/internal/mentions/service.go`
|
||||
- `apps/backend/internal/mentions/types.go`
|
||||
- `apps/backend/internal/mentions/service_test.go`
|
||||
- `apps/backend/internal/backendapp/mentions.go`
|
||||
- `apps/backend/internal/backendapp/mentions_test.go`
|
||||
- `apps/backend/internal/plugins/mentions.go`
|
||||
- Focused plugin bridge tests under `apps/backend/internal/plugins/`.
|
||||
- `apps/web/hooks/use-entity-reference-search.test.ts`
|
||||
- `apps/web/components/task/chat/use-entity-reference-composer.test.ts`
|
||||
- `apps/web/components/task/chat/entity-reference-menu.test.tsx`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 01 and 03.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Plugins dynamically register/unregister only manifest-owned `(source, provider,
|
||||
kind)` descriptors; source collisions, disabled plugins, timeouts, and cancellation
|
||||
have deterministic behavior.
|
||||
2. Host, not plugin, constructs canonical references. Search and message submission
|
||||
call live plugin authorization with verified workspace and `search`/`submission`
|
||||
purpose.
|
||||
3. Generic composer UI renders plugin pull-request groups/icons/chips without a
|
||||
Bitbucket frontend branch.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps/backend && go test ./internal/mentions ./internal/backendapp ./internal/plugins
|
||||
cd apps/web && pnpm test -- hooks/use-entity-reference-search.test.ts components/task/chat/use-entity-reference-composer.test.ts components/task/chat/entity-reference-menu.test.tsx
|
||||
cd apps/web && pnpm run typecheck
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Search results are untrusted presentation data. Submission reauthorization is required
|
||||
to prevent stale, tampered, cross-workspace, or disabled-plugin references entering
|
||||
message metadata.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
id: "06-plugin-owned-task-lifecycle"
|
||||
title: "Rich plugin-owned task lifecycle"
|
||||
status: completed
|
||||
wave: 2
|
||||
depends_on: ["01-design-package", "03-protocol-manifest-actions"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 06: Rich plugin-owned task lifecycle
|
||||
|
||||
## Intent
|
||||
|
||||
Let plugins create/read plugin-owned tasks with complete remote descriptors, launch
|
||||
profiles, namespaced metadata, and ownership-safe preview/cascade deletion.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/backend/internal/plugins/host_write.go`
|
||||
- `apps/backend/internal/plugins/host_data.go`
|
||||
- `apps/backend/internal/plugins/host_write_test.go`
|
||||
- `apps/backend/internal/plugins/host_data_test.go`
|
||||
- `apps/backend/internal/plugins/host_data_wire_test.go`
|
||||
- `apps/backend/internal/backendapp/services.go`
|
||||
- `apps/backend/internal/backendapp/adapters_plugin_starter.go`
|
||||
- `apps/backend/internal/task/service/service_requests.go`
|
||||
- `apps/backend/internal/task/service/service_tasks.go`
|
||||
- `apps/backend/internal/task/service/remote_repository_test.go`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 01 and 03.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Create/read shapes support existing repository ID or complete arbitrary-provider
|
||||
remote descriptor, workflow/step, plan, agent/executor profile, prompt/plan mode,
|
||||
and namespaced metadata.
|
||||
2. Host writes reserved `metadata.source = plugin:<id>`, rejects reserved-key
|
||||
overwrite, exposes executor-profile reads behind `api_read:executor_profiles`, and
|
||||
preserves exact credential-free Data Center clone URLs.
|
||||
3. Preview/delete only cascades trees whose source matches caller plugin; adopted or
|
||||
user-owned tasks survive.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps/backend && go test ./internal/plugins ./internal/task/service ./internal/backendapp ./pkg/pluginsdk
|
||||
make -C apps/backend lint
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Task provenance is destructive-action authorization. Missing or mismatched ownership
|
||||
must fail closed; do not use plugin state links as authority to delete user tasks.
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
id: "07-provider-neutral-git-credentials"
|
||||
title: "Provider-neutral Git credential broker"
|
||||
status: completed
|
||||
wave: 2
|
||||
depends_on: ["01-design-package", "03-protocol-manifest-actions"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 07: Provider-neutral Git credential broker
|
||||
|
||||
## Intent
|
||||
|
||||
Extract generic broker lease mechanics, retain GitHub via adapter, and route plugin
|
||||
credential resolution through scoped opaque helper leases for clone/fetch/push.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/backend/internal/gitcredentials/`
|
||||
- `apps/backend/internal/github/credential_broker.go`
|
||||
- `apps/backend/internal/repoclone/clone.go`
|
||||
- `apps/backend/internal/repoclone/protocol.go`
|
||||
- `apps/backend/internal/orchestrator/executor/executor.go`
|
||||
- `apps/backend/internal/orchestrator/executor/executor_credentials.go`
|
||||
- `apps/backend/internal/orchestrator/executor/executor_execute.go`
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/remote_github_env.go`
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/broker_reachability.go`
|
||||
- `apps/backend/internal/backendapp/orchestrator.go`
|
||||
- Focused `internal/gitcredentials`, clone, executor, and lifecycle tests.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 01 and 03.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Composite resolver supports arbitrary manifest-declared provider IDs and optional
|
||||
plugin credential RPCs while retaining current GitHub behavior unchanged.
|
||||
2. Leases bind exact workspace/task/session/repository/host/path, expire/revoke on all
|
||||
required lifecycle changes, re-resolve after OAuth refresh, and use HTTPS for remote
|
||||
executor broker transport.
|
||||
3. Clone/fetch/push preserve `RepositoryCloneURL` precedence and leave no credential in
|
||||
URLs, task state, logs, environment, command arguments, or executor payloads.
|
||||
4. Initial host clone requests carry exact task, active-session, and persisted-repository
|
||||
scope through the orchestrator and workspace-source materializer. Plugin providers
|
||||
reject missing scope; GitHub legacy behavior remains unchanged.
|
||||
5. Pre-worktree refresh for plugin providers uses the same exact scope, is strict, and
|
||||
suppresses every later unauthenticated fetch/pull while consuming refreshed refs.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps/backend && go test ./internal/gitcredentials ./internal/github ./internal/repoclone ./internal/orchestrator/executor ./internal/agent/runtime/lifecycle
|
||||
cd apps/backend && go test ./internal/backendapp ./internal/orchestrator/executor ./internal/repoclone
|
||||
make -C apps/backend lint
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Credential leakage and scope confusion are security failures. Treat host/path mismatch,
|
||||
disabled plugin, expired lease, and unsupported resolver as deny-by-default.
|
||||
|
||||
## Completed verification (2026-08-06)
|
||||
|
||||
- Focused clone, worktree, executor, lifecycle, and backend-app suites passed, including
|
||||
strict exact-scope refresh and no-network-after-refresh regressions.
|
||||
- `make -C apps/backend lint` passed (with only the known stale external-worktree filter
|
||||
warning).
|
||||
- A live Bitbucket Cloud task prepared in 16 ms with only `git checkout`, performed no
|
||||
second unauthenticated fetch, launched Codex, and reached `WAITING_FOR_INPUT` with `OK`.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
id: "08-native-repository-provider"
|
||||
title: "Native repository provider in task creation"
|
||||
status: completed
|
||||
wave: 2
|
||||
depends_on: ["01-design-package", "04-frontend-plugin-registry"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 08: Native repository provider in task creation
|
||||
|
||||
## Intent
|
||||
|
||||
Move native remote repository selection, branch listing, and pull-request inspection
|
||||
through repository-provider registry adapters without new host Bitbucket parsing.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/web/hooks/domains/integrations/use-remote-repositories.ts`
|
||||
- `apps/web/hooks/domains/integrations/use-remote-repositories.test.tsx`
|
||||
- `apps/web/hooks/domains/github/use-branches-by-url.ts`
|
||||
- `apps/web/hooks/domains/github/use-branches-by-url.test.ts`
|
||||
- `apps/web/hooks/domains/github/use-pr-info-by-url.ts`
|
||||
- `apps/web/hooks/domains/github/use-pr-info-by-url.test.ts`
|
||||
- `apps/web/components/task-create-dialog-types.ts`
|
||||
- `apps/web/components/task-create-dialog-state.ts`
|
||||
- `apps/web/components/task-create-dialog-state.test.ts`
|
||||
- `apps/web/components/task-create-dialog-helpers.ts`
|
||||
- `apps/web/components/task-create-dialog-helpers.test.ts`
|
||||
- `apps/web/components/task-create-dialog-remote-repo-provider-tabs.tsx`
|
||||
- `apps/web/components/task-create-dialog-remote-repo-provider-tabs.test.tsx`
|
||||
- `apps/web/components/task-create-dialog-remote-repo-identity.ts`
|
||||
- `apps/web/components/task-create-dialog-remote-repo-identity.test.ts`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 01 and 04.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Registry adapters drive built-in and plugin repository discovery, branch selection,
|
||||
and URL inspection; unknown self-managed URLs no longer default to GitLab.
|
||||
2. Provider-neutral state uses `remoteUrl` while preserving `githubUrl` caller
|
||||
compatibility during migration.
|
||||
3. Plugin-inspected URLs produce a complete descriptor for backend validation, including
|
||||
Cloud/DC custom host and exact clone URL behavior.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps/web && pnpm test -- hooks/domains/integrations/use-remote-repositories.test.tsx hooks/domains/github/use-branches-by-url.test.ts hooks/domains/github/use-pr-info-by-url.test.ts components/task-create-dialog-helpers.test.ts components/task-create-dialog-remote-repo-provider-tabs.test.tsx components/task-create-dialog-remote-repo-identity.test.ts
|
||||
cd apps/web && pnpm run typecheck
|
||||
cd apps && pnpm --filter @kandev/web lint
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Provider hint alone is untrusted. Preserve legacy callers while ensuring a plugin
|
||||
provider descriptor—not a host Bitbucket parser—crosses the backend boundary.
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: "09-native-link-review-surfaces"
|
||||
title: "Native Link and review surfaces"
|
||||
status: completed
|
||||
wave: 2
|
||||
depends_on: ["01-design-package", "04-frontend-plugin-registry"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 09: Native Link and review surfaces
|
||||
|
||||
## Intent
|
||||
|
||||
Dispatch Link actions and review rendering through plugin registry providers while
|
||||
keeping GitHub/GitLab compatibility and desktop/mobile feature parity.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/web/components/kanban-card-menu-items.tsx`
|
||||
- `apps/web/components/kanban-card-menu-items.test.tsx`
|
||||
- `apps/web/components/task/task-switcher-context-menu.tsx`
|
||||
- `apps/web/components/task/task-session-sidebar-link-actions.ts`
|
||||
- `apps/web/components/task/review-panel-provider.ts`
|
||||
- `apps/web/components/task/review-panel-provider.test.ts`
|
||||
- `apps/web/components/task/review-detail-panel.tsx`
|
||||
- `apps/web/components/task/dockview-panel-content.tsx`
|
||||
- `apps/web/components/task/dockview-shared.tsx`
|
||||
- `apps/web/components/task/dockview-session-tabs.ts`
|
||||
- `apps/web/components/task/dockview-session-tabs.test.ts`
|
||||
- `apps/web/lib/state/dockview-panel-actions.ts`
|
||||
- `apps/web/lib/state/dockview-panel-actions.test.ts`
|
||||
- `apps/web/lib/state/dockview-store.ts`
|
||||
- `apps/web/lib/state/dockview-store.test.ts`
|
||||
- `apps/web/components/task/dockview-add-panel-items.tsx`
|
||||
- `apps/web/components/task/task-center-panel.tsx`
|
||||
- `apps/web/components/task/mobile/session-mobile-layout.tsx`
|
||||
- `apps/web/components/task/mobile/session-mobile-layout.test.tsx`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 01 and 04.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. `registerTaskAction` renders Link-group actions—including **Link → Bitbucket Pull
|
||||
Request**—in existing desktop and visible mobile menus, closes before invocation,
|
||||
and passes read-only current context.
|
||||
2. Registered reviews use normalized items and external-store refresh in selectors,
|
||||
dock/detail panels, task center, auto-open/close, task switching, and mobile
|
||||
navigation; plugin `ReviewPanel` renders in those native locations.
|
||||
3. Provider-neutral panel IDs/params preserve saved-layout aliases `pr-detail`,
|
||||
`mr-detail`, `prKey`, and `mrKey`; unload removes plugin UI safely.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
cd apps/web && pnpm test -- components/kanban-card-menu-items.test.tsx components/task/review-panel-provider.test.ts components/task/dockview-session-tabs.test.ts lib/state/dockview-panel-actions.test.ts lib/state/dockview-store.test.ts components/task/mobile/session-mobile-layout.test.tsx
|
||||
cd apps/web && pnpm run typecheck
|
||||
cd apps && pnpm --filter @kandev/web lint
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Link/menu placement and mobile discoverability are product contracts. Do not replace
|
||||
native panels with a standalone route or remove legacy layout restoration.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
id: "10-cloud-dc-domain-auth"
|
||||
title: "Cloud/Data Center domain and authentication"
|
||||
status: completed
|
||||
wave: 3
|
||||
depends_on: ["01-design-package", "02-plugin-repository-bootstrap", "03-protocol-manifest-actions"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 10: Cloud/Data Center domain, HTTP clients, and authentication
|
||||
|
||||
## Intent
|
||||
|
||||
Implement the plugin-owned common Bitbucket domain and separate Cloud/Data Center
|
||||
adapters with secure workspace-scoped connection/auth lifecycle.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- Attached `kdlbs/kandev-plugin-bitbucket` worktree: domain models, Cloud adapter, Data
|
||||
Center adapter, HTTP clients, encrypted secret/state store, OAuth/token flows, health
|
||||
probe, redaction, and their fixture tests.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 01, 02, and 03.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Cloud uses `https://api.bitbucket.org/2.0` cursor pagination and API-token/OAuth
|
||||
authentication; Data Center normalizes configured API/clone bases and supports
|
||||
`start`/`limit`, PAT/HTTP access token, and OAuth when application link permits.
|
||||
2. Adapters map into one domain with explicit capabilities; UI/business code has no
|
||||
scattered Cloud/DC checks. Unsupported Data Center versions/capabilities are
|
||||
visible, not implied supported.
|
||||
3. Secrets use workspace/generation encryption, PKCE/signed one-time OAuth state,
|
||||
rotation singleflight, redaction, HTTPS/redirect/timeout/response-cap policy, and
|
||||
~90-second health polling with jitter/backoff.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
make test
|
||||
make fmt-check
|
||||
make vet
|
||||
make build
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Data Center context paths, private networks, proxies, and supported releases vary.
|
||||
Never store URL credentials or ship OAuth client secrets; test capability probes and
|
||||
origin-locked redirect behavior with fixtures.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
id: "11-plugin-workflows-watches"
|
||||
title: "Plugin task, Git, linking, and watch workflows"
|
||||
status: completed
|
||||
wave: 3
|
||||
depends_on: ["03-protocol-manifest-actions", "05-dynamic-composer-reference-sources", "06-plugin-owned-task-lifecycle", "07-provider-neutral-git-credentials", "10-cloud-dc-domain-auth"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 11: Plugin task, Git, linking, and watch workflows
|
||||
|
||||
## Intent
|
||||
|
||||
Use released host seams to implement Bitbucket plugin actions/RPC handlers for task
|
||||
launching, scoped Git credentials, PR linking/creation, and durable watches.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- Attached `kdlbs/kandev-plugin-bitbucket` worktree: action/RPC handlers, task and
|
||||
Git workflow services, link storage, credential resolver, health poll integration,
|
||||
watch persistence/poller/recovery, events, and focused tests.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 03, 05, 06, 07, and 10.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Authenticated actions launch tasks from PRs, link/unlink tasks, create PRs from
|
||||
task branches, and resolve Git credentials without secrets crossing host boundaries.
|
||||
2. Plugin `pull_request` search and authorization use the live Cloud/DC adapter for
|
||||
both composer search and message submission; they do not bypass host canonicalization.
|
||||
3. Watches persist definition/cursor/dedupe/reservation/link/recovery state, use keyed
|
||||
mutex plus durable `creating` reservation, reconcile crashes, and emit
|
||||
`plugin.kandev-plugin-bitbucket.*` events.
|
||||
4. Reset/delete previews cascade and removes only plugin/watch-owned task trees;
|
||||
manually linked and adopted tasks survive.
|
||||
5. The Cloud/Data Center provider wrapper preserves restart-safe PR paging; a
|
||||
watch-created task is returned by both task-scoped PR and workspace-association
|
||||
queries after restart.
|
||||
6. Creating a PR from a verified task persists its association immediately. A remote
|
||||
create success followed by local association failure returns a bounded partial
|
||||
result rather than a retryable error that could duplicate the remote PR.
|
||||
7. Review status adapters query the PR source/head commit.
|
||||
8. Task-scoped refresh performs bounded, exact source-branch PR discovery from the
|
||||
host-verified repository checkout and persists the result idempotently; discovery
|
||||
errors do not suppress existing associations.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
make test
|
||||
make vet
|
||||
make build
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Concurrent polls and crash timing can duplicate tasks. Credential refresh and ownership
|
||||
checks must fail closed; avoid adding Bitbucket logic to host `agentctl` PR automation.
|
||||
|
||||
## Completion
|
||||
|
||||
- Live Cloud acceptance proved manual linking through the host-native dialog and durable
|
||||
association recovery after host/plugin restarts.
|
||||
- A disposable linked task was explicitly unlinked, then task-scoped refresh rediscovered
|
||||
the open pull request by its exact host-verified `kandev-live-test` checkout branch and
|
||||
persisted the association again (`0 -> discovered key -> 1`).
|
||||
- The live watch created exactly one owned task and a subsequent run skipped the same pull
|
||||
request. Cloud paging now respects Bitbucket's 50-item maximum.
|
||||
- Review status reads the source commit: the live `KANDEV-LIVE-ACCEPTANCE` marker resolved
|
||||
target `c1c53106bebf`, not the destination commit.
|
||||
- Final plugin checks passed: 37 UI tests, `go test ./...`, `go test -race ./internal/...`,
|
||||
`go vet ./...`, host build, five-platform package build, and checksum verification.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
id: "12-plugin-ui-native-registrations"
|
||||
title: "Plugin UI and native registrations"
|
||||
status: completed
|
||||
wave: 3
|
||||
depends_on: ["04-frontend-plugin-registry", "05-dynamic-composer-reference-sources", "08-native-repository-provider", "09-native-link-review-surfaces", "10-cloud-dc-domain-auth"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 12: Plugin UI and native registrations
|
||||
|
||||
## Intent
|
||||
|
||||
Build plugin-owned settings, queue, review, and mobile UI; register it with native
|
||||
repository, task-action, review-provider, and reference-source contracts.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- Attached `kdlbs/kandev-plugin-bitbucket` worktree: TypeScript UI bundle, route/nav,
|
||||
connection/settings components, queue/review panels, native registration module,
|
||||
responsive styles, view-model/component tests, and plugin Playwright tests.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 04, 05, 08, 09, and 10.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Native **Settings > Integrations > Bitbucket** provides connection/authentication,
|
||||
health, and saved-watch configuration; `/bitbucket` provides browse/search, queue
|
||||
filters, review details, status presentation, and task launch/link/unlink/create-PR
|
||||
through authenticated plugin actions.
|
||||
2. Plugin registers provider `bitbucket`, Link actions, native review panel, and
|
||||
`bitbucket`/`pull_request` composer source; its review component works in host
|
||||
desktop and mobile surfaces.
|
||||
3. Mobile uses focused list/detail route state, one scroll owner, `100dvh`, safe areas,
|
||||
>=44px controls, and Drawers for filters/actions rather than compressed panes.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
pnpm e2e
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Capability flags must remove or explain unavailable Cloud/DC controls. Do not duplicate
|
||||
host UI or add a Bitbucket-specific frontend branch; plugin unload must tolerate
|
||||
remounting and remove its registrations.
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
id: "12b-github-parity-page"
|
||||
title: "Rebuild Bitbucket page with GitHub list parity"
|
||||
status: completed
|
||||
wave: 3b
|
||||
depends_on: ["12-plugin-ui-native-registrations"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 12b: Rebuild Bitbucket page with GitHub list parity
|
||||
|
||||
## Intent
|
||||
|
||||
Replace the live-evaluation desktop split workbench with the first-party `/github`
|
||||
page's list-first hierarchy while retaining plugin-owned review depth, watches, Cloud
|
||||
and Data Center capability handling, and native mobile parity.
|
||||
|
||||
## Confirmed cause
|
||||
|
||||
`ui/src/bundle.ts` renders `.bb-desktop-panes`, permanently allocating a narrow queue
|
||||
and an empty review pane. `apps/web/app/github/github-page-client.tsx` instead composes
|
||||
`PresetsScopeBar`, `ListToolbar`, one padded full-width `PRList`, and an optional
|
||||
pagination footer. Source, installed, and served plugin asset hashes matched during
|
||||
reproduction, so stale files did not cause the reported layout.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- Attached `kdlbs/kandev-plugin-bitbucket` worktree:
|
||||
- `ui/src/bundle.ts`
|
||||
- `ui/src/view-models.ts`
|
||||
- `ui/plugin.css`
|
||||
- `ui/bundle.js`
|
||||
- `ui/test/registrations.test.ts`
|
||||
- `ui/test/view-models.test.ts`
|
||||
- `ui/e2e/desktop-packaged-plugin.spec.ts`
|
||||
- `ui/e2e/mobile-packaged-plugin.spec.ts`
|
||||
|
||||
## Implementation
|
||||
|
||||
1. Add tested review-query URL helpers so `/bitbucket?review=<canonical-key>` is a
|
||||
reloadable focused-detail state and Back returns to `/bitbucket`.
|
||||
2. Replace `.bb-desktop-panes` with a full-height list layout matching GitHub's order:
|
||||
desktop scope pills, compact title/count + repository/query + refresh/watch toolbar,
|
||||
then one padded, bordered, divided result list.
|
||||
3. Match GitHub row density and anatomy: provider-colored PR state icon, linked title,
|
||||
repository/number and readable author metadata, restrained status, compact Task and
|
||||
Review affordances. Hide provider-opaque account identifiers from display.
|
||||
4. Reuse `ReviewDetailPanel` as focused page content and native task ReviewPanel; do
|
||||
not duplicate review action logic.
|
||||
5. Keep phone composition one-dimensional: compact list toolbar, filter Drawer,
|
||||
direct focused detail, 44px controls, safe-area padding, and one scroll owner.
|
||||
|
||||
## Mobile design contract
|
||||
|
||||
- Desktop outcome: scan full-width results and launch a task, open Bitbucket, or open
|
||||
focused review without a permanent detail pane.
|
||||
- Mobile entry: `/bitbucket`; closest exemplar is `/github` list/filter hierarchy plus
|
||||
`apps/web/components/kanban-with-preview.tsx` direct detail navigation.
|
||||
- Hierarchy: topbar → compact toolbar → PR list → focused review. Primary row action is
|
||||
Review; filters/actions are temporary Drawers.
|
||||
- Scroll: list or focused review owns vertical scroll, never both; viewport-bound
|
||||
content uses `100dvh`, overscroll containment, and bottom safe-area clearance.
|
||||
- Shared query/filter/review state and view-model helpers serve both compositions.
|
||||
|
||||
## RED tests
|
||||
|
||||
- `ui/test/view-models.test.ts`: review URL encoding/decoding and opaque-author display.
|
||||
- `ui/test/registrations.test.ts`: GitHub-parity markers exist and permanent split-pane
|
||||
markers do not.
|
||||
- Desktop Playwright: full-width list exists, no review pane exists initially, Review
|
||||
changes URL and focuses detail, Back restores list.
|
||||
- Mobile Playwright: same URL/back outcome, filter/action Drawers remain contained,
|
||||
touch targets remain at least 44px, and document has no horizontal overflow.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
npm test
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run e2e
|
||||
test -z "$(gofmt -l .)"
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Completed verification: 27 Vitest checks plus typecheck/build passed; seven packaged
|
||||
desktop/mobile Playwright scenarios passed against the live Cloud-connected instance.
|
||||
Fresh desktop and mobile documents rendered without browser console errors.
|
||||
|
||||
Then copy only `ui/bundle.js` and `ui/plugin.css` into the running disposable plugin
|
||||
installation, hard-reload a fresh document, and capture `/github` and `/bitbucket` at
|
||||
identical desktop/mobile viewport sizes. Do not replace the live plugin server binary.
|
||||
|
||||
## Risks
|
||||
|
||||
- Bitbucket queue actions currently expose a bounded result set without total/cursor;
|
||||
match GitHub's list hierarchy but do not fabricate pagination totals.
|
||||
- Review query keys must remain encoded and must not become a host-specific route.
|
||||
- Cloud can return canonical opaque account IDs; presentation must omit those rather
|
||||
than exposing unreadable identifiers or changing authorization identity semantics.
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
id: "12c-exact-code-host-ui-parity"
|
||||
title: "Use exact shared GitHub/GitLab dashboard and task flow"
|
||||
status: completed
|
||||
wave: 3c
|
||||
depends_on: ["12b-github-parity-page"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
|
||||
---
|
||||
|
||||
# Task 12c: Use exact shared GitHub/GitLab dashboard and task flow
|
||||
|
||||
## Intent
|
||||
|
||||
Replace visual approximation and plugin-invented actions with the actual host-rendered
|
||||
GitHub/GitLab dashboard contract. Preserve Bitbucket API/domain ownership and native
|
||||
task review-provider depth.
|
||||
|
||||
## Confirmed mismatch
|
||||
|
||||
GitHub `PRList` and GitLab `MRList` render inert rows whose title opens the provider
|
||||
and whose sole action is a compact **Task** preset dropdown. Preset selection opens
|
||||
`TaskCreateDialog` directly. Bitbucket rendered equal **Task** and **Review** buttons,
|
||||
then added an intermediate preset modal before server-side task creation. Served and
|
||||
source hashes matched, so stale assets did not cause the mismatch.
|
||||
|
||||
Manual follow-up found two remaining parity regressions: Bitbucket scope pills changed
|
||||
an out-of-band state parameter without committing the matching visible query, while
|
||||
GitHub commits every preset filter into its query field; and Bitbucket used hand-drawn
|
||||
SVG paths instead of GitHub/GitLab's host Tabler glyphs.
|
||||
|
||||
A second manual follow-up found that the Task preset rows still all used the generic
|
||||
checklist fallback, because the plugin could not select the host's exact eye, message,
|
||||
and tool preset icons. It also found no task-topbar CI status/popover contribution, so
|
||||
linked Bitbucket pipelines were visible only inside the full review panel.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- Host:
|
||||
- `apps/web/components/integrations/**`
|
||||
- `apps/web/components/github/my-github/{pr-list,list-toolbar}.tsx`
|
||||
- `apps/web/components/gitlab/my-gitlab/{mr-list,list-toolbar,start-task-menu}.tsx`
|
||||
- `apps/web/lib/plugins/{host-api,types}.ts` and focused tests
|
||||
- plugin authoring/API docs and this feature's spec/plan/ADR
|
||||
- `kdlbs/kandev-plugin-bitbucket`:
|
||||
- `ui/**`
|
||||
- `internal/{domain,cloud,datacenter,plugin}/**`
|
||||
- `manifest.yaml`
|
||||
|
||||
## Implementation
|
||||
|
||||
1. Extract provider-neutral `ChangeRequestList`/row, task preset menu, and list
|
||||
toolbar under `components/integrations`; refactor GitHub and GitLab to consume them
|
||||
before exposing them with `IntegrationScopeBar` and `TaskRowIndicator` on `host.ui`.
|
||||
2. Add human display-author and creation-time fields without replacing provider-
|
||||
canonical authorization identity. Add a provider-free association action that
|
||||
paginates workspace tasks and reads task-scoped Bitbucket link state.
|
||||
3. Render Bitbucket results with the shared host components. Remove the row Review
|
||||
action, dashboard Watch action, and `/bitbucket?review=...` dashboard flow; retain
|
||||
`ReviewDetailPanel` only for the registered native task ReviewPanel. Watches remain
|
||||
in native integration settings.
|
||||
4. Use GitHub/GitLab's **Review**, **Address feedback**, and **Fix CI** task presets.
|
||||
Selecting one mounts `host.ui.TaskCreateDialog` immediately with matched repository,
|
||||
source branch, task title, and prompt; successful creation links the PR and routes
|
||||
to the task.
|
||||
5. Render linked tasks through the same host `TaskRowIndicator`; keep provider title
|
||||
external and row container inert.
|
||||
6. Export host-owned semantic integration icons, use them for Bitbucket scope and row
|
||||
states, and keep runtime UI in the host repository rather than a shared UI repo.
|
||||
7. Make Bitbucket's visible committed query the source of truth for scope state:
|
||||
selecting Open/All/Merged/Declined writes and commits the normalized state token;
|
||||
committing a query drives the same state sent to Cloud/Data Center.
|
||||
8. Add semantic preset icon names to the shared menu and make GitHub and plugins resolve
|
||||
them through one host mapping; Bitbucket sends eye/message/tool for the three native
|
||||
presets.
|
||||
9. Add the provider-neutral host `IntegrationChangeRequestStatus` control and
|
||||
`openTaskReview` callback. Register Bitbucket in `chat-top-bar`, refresh linked PR
|
||||
statuses on open and around every 90 seconds, and use the same desktop hover/mobile
|
||||
drawer interaction as GitHub.
|
||||
|
||||
## Mobile design contract
|
||||
|
||||
- Entry and hierarchy match `/github` and `/gitlab`: topbar, temporary filter Sheet,
|
||||
compact list toolbar, full-width change-request list.
|
||||
- Row title opens Bitbucket. **Task** is the only row action; its host DropdownMenu
|
||||
receives Kandev's phone bottom-surface treatment and 44px trigger/items.
|
||||
- Task creation uses the same native responsive `TaskCreateDialog`; review uses the
|
||||
host's task Review surface. No extra plugin Drawer or mobile dashboard detail route.
|
||||
- Document has one vertical scroll owner and no horizontal overflow; shared host
|
||||
components own responsive geometry, while plugin state/query logic remains shared.
|
||||
|
||||
## TDD and verification
|
||||
|
||||
1. RED host tests for missing `host.ui` exports and shared row/task-menu behavior.
|
||||
2. RED plugin unit/E2E tests asserting one **Task** dropdown, no **Review** button,
|
||||
direct native task dialog, linked-task refresh, and matching desktop/mobile flow.
|
||||
3. RED Cloud/Data Center/workflow tests for display metadata and association paging.
|
||||
4. Run focused host component/plugin API tests, GitHub/GitLab regressions, plugin unit
|
||||
and race tests, typecheck/lint/build, packaged desktop/mobile E2E, then live Cloud.
|
||||
5. Compare fresh `/github`, `/gitlab`, and `/bitbucket` desktop/mobile screenshots;
|
||||
require source, installed, and served asset hashes to match with zero console errors.
|
||||
|
||||
## Risks
|
||||
|
||||
- New `host.ui` exports require a named host release before plugin publication.
|
||||
- Task linking happens after host task creation; failures must not claim association
|
||||
success and must preserve navigation to the successfully created task.
|
||||
- Provider display names are presentation-only; canonical account IDs remain the
|
||||
authorization identity and never get silently substituted.
|
||||
- Shared primitives must stay provider-neutral; importing Bitbucket types or API logic
|
||||
into the host fails this task.
|
||||
|
||||
## Completion
|
||||
|
||||
- GitHub, GitLab, and Bitbucket now consume the same host-owned change-request list,
|
||||
toolbar, task menu, and linked-task indicator primitives.
|
||||
- The live Cloud package presents one **Task** menu, opens `TaskCreateDialog` directly,
|
||||
keeps review in the linked task, and has no dashboard Review or Watch action.
|
||||
- Verification passed: 1,010 host test files / 7,712 tests, focused host typecheck/lint/
|
||||
production build, 29 plugin UI tests, plugin Go race/vet/package checks, and eight
|
||||
live Cloud desktop/mobile Playwright checks.
|
||||
- The manual follow-up is complete: preset clicks commit `state:*` into the visible
|
||||
query, committed queries drive provider requests, and Bitbucket consumes the same
|
||||
host-owned semantic Tabler icons as GitHub/GitLab.
|
||||
- Final browser acceptance verified the exact host preset glyph classes: `IconEye`,
|
||||
`IconMessageDots`, and `IconTool`. The native task dialog loaded both live Bitbucket
|
||||
branches through the persisted provider bridge with HTTP 200 instead of a GitHub
|
||||
fallback/500.
|
||||
- The host-native task-link dialog issued `pullrequests.link` successfully and all three
|
||||
disposable manual, auto-discovered, and watch-created tasks remained associated after
|
||||
restart.
|
||||
- The task-topbar pipeline control passed desktop and native-touch acceptance. Opening it
|
||||
refreshed live status, desktop hover rendered the pipeline popover/link, mobile used a
|
||||
bounded no-overflow drawer with 44px controls, and both opened native Review. A live
|
||||
90-second polling cycle tracked `SUCCESSFUL -> INPROGRESS -> SUCCESSFUL`, changing the
|
||||
host glyph `check -> clock -> check`; the fixture was restored to `SUCCESSFUL`.
|
||||
- Final focused host verification passed 154 tests, web typecheck, backend lint/build,
|
||||
plugin 37 UI tests, Go unit/race/vet/build, and five-platform package checksums.
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
id: "12d-host-native-task-link-parity"
|
||||
title: "Use the host-native task change-request link dialog"
|
||||
status: completed
|
||||
wave: 3d
|
||||
depends_on: ["12c-exact-code-host-ui-parity"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
|
||||
---
|
||||
|
||||
# Task 12d: Use the host-native task change-request link dialog
|
||||
|
||||
## Confirmed root cause
|
||||
|
||||
`TaskActionRegistration.run()` supplied verified task context but no native linking
|
||||
surface. The Bitbucket plugin therefore used `host.openModal()` and hand-built a form
|
||||
whose width, description placement, footer, validation, success handling, mobile
|
||||
presentation, and icon differed from `TaskGitHubPRDialog`. Existing tests asserted only
|
||||
action invocation and modal presence. The real plugin also registered “Link Bitbucket
|
||||
Pull Request” even though the fixture and built-in submenu items name only their target.
|
||||
|
||||
## Implementation
|
||||
|
||||
1. Extract GitHub's one-input link form into a provider-neutral host component with
|
||||
native inline errors, Cancel/Save footer, submitting state, toast, and close behavior.
|
||||
2. Add an additive `host.openTaskLinkDialog()` contract that mounts that exact component
|
||||
in host-owned dialog geometry; refactor GitHub to consume the shared form first.
|
||||
3. Propagate registered plugin icon names into both task-card and task-switcher Link
|
||||
menus instead of substituting a generic link glyph.
|
||||
4. Register Bitbucket as **Bitbucket Pull Request**, submit its parsed reference through
|
||||
the authenticated `pullrequests.link` action, and remove its copied link form.
|
||||
5. Update the in-tree fixture and desktop/mobile E2E to prove native anatomy, validation,
|
||||
action invocation, close-on-success, toast, icon, and menu copy.
|
||||
|
||||
## Mobile contract
|
||||
|
||||
- Entry remains the visible task actions menu and its existing **Link** submenu.
|
||||
- Nearest exemplar is `TaskGitHubPRDialog`; Bitbucket uses the same dialog instead of a
|
||||
plugin-only bottom drawer so behavior and focus return remain identical.
|
||||
- One dialog owns scrolling; input and footer actions remain touch reachable without
|
||||
document horizontal overflow.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
cd apps && pnpm --filter @kandev/web exec vitest run \
|
||||
components/integrations/task-change-request-link-form.test.tsx \
|
||||
components/task/task-github-pr-dialog.test.tsx \
|
||||
components/plugins/plugin-modal-host.test.tsx \
|
||||
components/kanban-card-menu-items.test.tsx \
|
||||
lib/plugins/host-api.test.ts
|
||||
cd ../kdlbs-kandev-plugin-bitbucket && npm test
|
||||
cd ../kandev-2/apps/web && pnpm e2e:run e2e/tests/plugins/bitbucket-plugin-contract.spec.ts
|
||||
```
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Both Link menus show a Bitbucket brand icon and **Bitbucket Pull Request**.
|
||||
- GitHub and Bitbucket render the same form anatomy and interaction states.
|
||||
- Invalid input stays open with inline error; success links once, closes, and toasts.
|
||||
- Desktop and mobile E2E complete the same user outcome with no overflow.
|
||||
- Full current-worktree review records any unrelated blockers before merge readiness.
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: "12e-shared-task-status"
|
||||
title: "Render registered provider status in exact host task chrome"
|
||||
status: completed
|
||||
wave: 3e
|
||||
depends_on: ["12d-host-native-task-link-parity"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
|
||||
---
|
||||
|
||||
# Task 12e: Render registered provider status in exact host task chrome
|
||||
|
||||
## Intent
|
||||
|
||||
Make status presentation impossible for a code-host plugin to visually fork. Extend the
|
||||
existing review-provider data contract and have Kandev mount the exact shared topbar and
|
||||
composer CI surfaces for registered providers.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/web/lib/plugins/{types,registry,host-api}.ts` and focused tests
|
||||
- `apps/web/components/task/review-panel-provider.ts` and tests
|
||||
- `apps/web/components/integrations/change-request-status-*.tsx` and tests
|
||||
- `apps/web/components/github/{pr-topbar-button,pr-status-chip,pr-ci-popover}.tsx`
|
||||
- `apps/web/components/task/{task-top-bar,passthrough-toolbar}.tsx`
|
||||
- `apps/web/components/task/chat/chat-input-area.tsx`
|
||||
- plugin API/authoring docs
|
||||
|
||||
## Implementation
|
||||
|
||||
1. Add an optional normalized `taskStatus` to `ReviewItemSummary`, preserving it through
|
||||
registry validation without accepting provider-specific payloads.
|
||||
2. Extract the GitHub topbar trigger, composer chip, and common CI popover/drawer body
|
||||
into provider-neutral host components. Adapt GitHub to those components first.
|
||||
3. Build one registry-backed status adapter from `useNormalizedTaskReviews`; refresh via
|
||||
the provider's existing deduplicated lifecycle and background interval.
|
||||
4. Mount it beside `PRTopbarButton`, beside `PRStatusChip`, and in passthrough status.
|
||||
Avoid a new plugin visual slot or second provider poller.
|
||||
5. Keep optional GitHub-only automation/merge callbacks in the shared anatomy without
|
||||
requiring them from Bitbucket.
|
||||
|
||||
## TDD and acceptance
|
||||
|
||||
1. RED registry tests prove normalized status is currently discarded.
|
||||
2. RED task-topbar, chat-status, and passthrough tests require registered-provider
|
||||
topbar and composer entries, exact shared popover content, refresh routing, and unload.
|
||||
3. GREEN implementation keeps all existing GitHub status tests unchanged or adapts only
|
||||
their provider-neutral import names.
|
||||
4. Run focused Vitest, web typecheck/lint, and desktop/mobile E2E assertions.
|
||||
|
||||
## Mobile contract
|
||||
|
||||
Touch uses the same bounded drawer as GitHub, one internal scroll owner, and controls at
|
||||
least 44px tall. Desktop and mobile expose the same checks and open-Review capability.
|
||||
|
||||
## Risks
|
||||
|
||||
- Provider snapshots must remain stable for `useSyncExternalStore`.
|
||||
- Background refresh must deduplicate topbar/composer consumers and abort on unload.
|
||||
- Built-in GitHub behavior, automation, and multi-PR aggregation cannot regress.
|
||||
|
||||
## Completed verification (2026-08-06)
|
||||
|
||||
- Nine focused host suites passed (70 tests), plus web typecheck and lint.
|
||||
- Desktop topbar and composer both rendered the shared `pr-topbar-popover-inner` anatomy.
|
||||
- Touch emulation rendered the shared bounded CI drawer with no horizontal overflow.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
id: "12f-shared-review-detail"
|
||||
title: "Extract the GitHub change-request detail as a host UI contract"
|
||||
status: completed
|
||||
wave: 3f
|
||||
depends_on: ["12d-host-native-task-link-parity"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
|
||||
---
|
||||
|
||||
# Task 12f: Extract the GitHub change-request detail as a host UI contract
|
||||
|
||||
## Intent
|
||||
|
||||
Use one host-owned review layout for GitHub and compatible plugin providers. Providers
|
||||
map data and actions; they do not recreate headers, tabs, sections, buttons, or mobile
|
||||
geometry.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/web/components/integrations/change-request-detail.tsx` and tests
|
||||
- `apps/web/components/github/pr-detail-panel.tsx` and focused regression tests
|
||||
- `apps/web/lib/plugins/{types,host-api}.ts` and focused tests
|
||||
- plugin API/authoring docs
|
||||
|
||||
## Implementation
|
||||
|
||||
1. Define a provider-neutral detail model for identity/state, author/timestamps,
|
||||
branches/stats, description, review summaries, checks, threaded comments, and sync
|
||||
time, plus capability-gated action descriptors/callbacks.
|
||||
2. Extract the pure presentation from GitHub `PRDetailContent` into
|
||||
`ChangeRequestDetail`; retain GitHub fetching, auth, feedback caching, and mutations
|
||||
in a GitHub adapter.
|
||||
3. Expose the component and its additive model through versioned `host.ui`.
|
||||
4. Preserve GitHub's header, collapsible Description/Reviews/Checks/Comments sections,
|
||||
action placement, loading/error treatment, and one-scroll-owner responsive layout.
|
||||
|
||||
## TDD and acceptance
|
||||
|
||||
1. RED component/API tests require the missing host component, model, action dispatch,
|
||||
and responsive semantics.
|
||||
2. GREEN GitHub adapter tests prove existing data and supported actions map without a
|
||||
visual regression.
|
||||
3. Run focused Vitest, web typecheck/lint, and existing GitHub review E2E coverage.
|
||||
|
||||
## Mobile contract
|
||||
|
||||
The component fills the native mobile Review location, owns no route or drawer, retains
|
||||
one vertical scroll owner, prevents horizontal overflow, and keeps action targets at
|
||||
least 44px.
|
||||
|
||||
## Risks
|
||||
|
||||
- Extraction must not weaken GitHub's auth-dependent approve/merge behavior.
|
||||
- Provider-neutral types cannot encode GitHub or Bitbucket REST payloads.
|
||||
- Unsupported actions must be absent, not disabled forever or replaced with new layout.
|
||||
|
||||
## Completed verification (2026-08-06)
|
||||
|
||||
- GitHub and registered providers now render the same host `ChangeRequestDetail` component.
|
||||
- Focused component/adapter tests, web typecheck, and lint passed.
|
||||
- Live desktop and touch runs rendered Description, Reviews, CI Checks, and Comments with
|
||||
one scroll owner and no horizontal overflow.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
id: "12g-bitbucket-status-detail-adapters"
|
||||
title: "Adapt Bitbucket to shared task status and review detail"
|
||||
status: completed
|
||||
wave: 3g
|
||||
depends_on: ["12e-shared-task-status", "12f-shared-review-detail"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
|
||||
---
|
||||
|
||||
# Task 12g: Adapt Bitbucket to shared task status and review detail
|
||||
|
||||
## Intent
|
||||
|
||||
Remove the plugin-owned status slot and bespoke tabbed Review panel. Feed Bitbucket
|
||||
Cloud/Data Center data and supported actions into the exact host surfaces from tasks
|
||||
12e and 12f, then prove live pipeline/link/review behavior.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `kdlbs/kandev-plugin-bitbucket/ui/src/{bundle,task-review-status,view-models}.ts`
|
||||
- `kdlbs/kandev-plugin-bitbucket/ui/{plugin.css,test/**,e2e/**}`
|
||||
- Bitbucket adapter/domain fixtures needed for normalized detail/status fields
|
||||
- packaged plugin bundle and manifest version
|
||||
|
||||
## Implementation
|
||||
|
||||
1. Hydrate review-provider snapshots with head-commit build statuses and normalized
|
||||
shared `taskStatus`; remove the `chat-top-bar` visual registration and its poller.
|
||||
2. Map Bitbucket identity/state, author/timestamps, branches/stats, description,
|
||||
participants/reviews, checks, threads, and supported mutations into
|
||||
`host.ui.ChangeRequestDetail`.
|
||||
3. Remove custom Review tabs/actions/CSS. Declare approve/unapprove/merge/decline,
|
||||
comment/reply, refresh, and external links only when Cloud/Data Center capabilities
|
||||
and viewer state permit them.
|
||||
4. Preserve durable manual, auto-discovered, created, and watch-owned PR association as
|
||||
the single source for review/status queries.
|
||||
5. Rebuild/package a fresh version and restart the evaluation instance with exact served
|
||||
asset hashes.
|
||||
|
||||
## TDD and acceptance
|
||||
|
||||
1. RED plugin tests require status in the registry snapshot, no visual slot, and exact
|
||||
normalized detail/action mapping; cover links objects without string coercion.
|
||||
2. RED desktop/mobile E2E requires topbar popover, composer CI chip, shared Review
|
||||
sections, action dispatch, provider links, no custom tabs, and no overflow.
|
||||
3. Live Cloud acceptance changes the source-commit pipeline
|
||||
`SUCCESSFUL -> INPROGRESS -> FAILED -> SUCCESSFUL`, verifies both status surfaces
|
||||
update, opens Review from each, and restores the fixture.
|
||||
4. Verify manual linking and exact-branch auto-link survive restart and feed both status
|
||||
surfaces. Data Center remains fixture-covered until a disposable target exists.
|
||||
5. Run plugin unit/race/vet/build/package checks plus focused host E2E.
|
||||
|
||||
## Risks
|
||||
|
||||
- Bitbucket Cloud and Data Center expose different build/review detail shapes; normalize
|
||||
capabilities without pretending unsupported operations exist.
|
||||
- Live acceptance must restore the disposable pipeline state even after a failed test.
|
||||
- Same-version bundle caching requires a version bump and fresh document.
|
||||
|
||||
## Completed verification (2026-08-06)
|
||||
|
||||
- Plugin UI tests passed (43), all Go packages passed, `go vet ./...` passed, and the
|
||||
host-only `0.1.10` package verified and installed active in the evaluation instance.
|
||||
- Live Cloud commit status completed the required
|
||||
`SUCCESSFUL -> INPROGRESS -> FAILED -> SUCCESSFUL` cycle; both shared status surfaces
|
||||
reflected each state and the fixture was restored.
|
||||
- Manual Link dialog submission persisted one association. Exact-branch auto-link was
|
||||
proved by unlinking the disposable task, observing zero associations, loading the task,
|
||||
and observing the matching PR association recreated.
|
||||
- Cloud review detail exposed real PR data/actions through the shared host component;
|
||||
Cloud and Data Center timestamp fixtures cover provider normalization, while a live
|
||||
Data Center target remains intentionally out of scope for this acceptance run.
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
id: "12h-native-create-unlink-indicators-saved-queries"
|
||||
title: "Close native create, unlink, task-indicator, and saved-query gaps"
|
||||
status: completed
|
||||
wave: 3h
|
||||
depends_on: ["12g-bitbucket-status-detail-adapters"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
decision: "../../decisions/2026-08-10-plugin-change-request-mutations.md"
|
||||
---
|
||||
|
||||
# Task 12h: Close Native Create, Unlink, Task-Indicator, and Saved-Query Gaps
|
||||
|
||||
## Intent
|
||||
|
||||
Fix four live-evaluation gaps without adding Bitbucket-specific host branches: route
|
||||
native create through a registered provider after Git push, expose shared unlink,
|
||||
hydrate native task indicators from one workspace association snapshot, and persist
|
||||
dashboard saved queries with GitHub/GitLab interaction parity.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/web/lib/plugins/{types,registry,registry-normalization}.ts` and focused tests
|
||||
- `apps/backend/internal/plugins/handlers.go` and authenticated-action tests
|
||||
- `apps/web/hooks/use-git-operations.ts`, `apps/web/components/vcs/**`, and focused tests
|
||||
- `apps/web/components/integrations/**`, task/sidebar/Kanban list placements, and tests
|
||||
- `docs/{decisions,specs,plans,public}/**` plugin contract documentation
|
||||
- Attached `kdlbs/kandev-plugin-bitbucket/{ui,internal,manifest.yaml}` implementation/tests
|
||||
|
||||
## Implementation
|
||||
|
||||
1. Extend repository-provider registration with lifecycle-cancelled native change-
|
||||
request creation and declared option support. Resolve only the persisted repository
|
||||
attached to the active task/repo scope; push through `worktree.push`, then call the
|
||||
provider. Keep built-in `worktree.create_pr` behavior unchanged.
|
||||
Extend task-scoped authenticated actions with an optional repository selector that
|
||||
the host accepts only when it is attached to the verified task.
|
||||
2. Extend review-provider registration with lifecycle-cancelled unlink and a normalized
|
||||
workspace association external store. Add host-owned unlink controls and semantic
|
||||
task indicators in desktop/mobile shared surfaces.
|
||||
3. Register Bitbucket create/unlink/association callbacks. Server create selects the
|
||||
host-verified repository ID, records the returned association, and remains safe after
|
||||
a successful push. Link/create/unlink refresh both review and association snapshots.
|
||||
4. Add `capabilities.user_state`, persist bounded workspace saved-query records through
|
||||
`host.storage`, and reuse host scope/dialog primitives for save/select/delete on
|
||||
desktop and mobile.
|
||||
5. Update public plugin API docs, rebuild the plugin bundle/package, and cover complete
|
||||
behavior in host fixture and packaged plugin E2E.
|
||||
|
||||
## TDD and acceptance
|
||||
|
||||
1. RED host tests pin provider resolution, push-before-create ordering, post-push retry,
|
||||
lifecycle abort, option visibility, association dedupe, unlink, and no-plugin parity.
|
||||
2. RED plugin tests pin authenticated create payloads, repository selection, link/unlink
|
||||
refresh, association snapshots, storage validation, named save/select/delete, and
|
||||
workspace isolation.
|
||||
3. Desktop/mobile E2E proves conditional native Create PR, resulting association,
|
||||
sidebar/Kanban glyph, shared unlink, multi-link preservation, saved-query reload and
|
||||
delete, and unload cleanup.
|
||||
4. Run focused frontend unit/type/lint checks, plugin UI/Go/race/build/package checks,
|
||||
and `git diff --check` in both repositories.
|
||||
|
||||
## Risks
|
||||
|
||||
- Push succeeds before remote creation; retry must not duplicate a pull request or hide
|
||||
the partial-success state.
|
||||
- Multi-repository tasks require exact repo-scope-to-persisted-repository resolution.
|
||||
- Association hydration must stay workspace-bounded and shared across many task rows;
|
||||
per-task provider polling is not acceptable.
|
||||
- `host.storage` is permission-gated; upgrade failure must remain visible and must not
|
||||
corrupt in-memory saved-query state.
|
||||
|
||||
## Completion evidence
|
||||
|
||||
- Native **Create PR** pushed the verified session checkout, dispatched
|
||||
`pullrequests.create` through the registered Bitbucket provider, received HTTP 201,
|
||||
and linked the returned pull request without adding Bitbucket logic to agentctl.
|
||||
- Shared desktop status hover exposed unlink; unlink removed topbar/composer status and
|
||||
sidebar indicator immediately and remained detached after a full reload.
|
||||
- Workspace association hydration rendered linked pull-request indicators across the
|
||||
sidebar from one provider snapshot.
|
||||
- A changed dashboard query enabled **Save current query**; the shared host dialog saved
|
||||
it, reload retained it, and selecting it restored the exact query.
|
||||
- Host focused frontend tests (100), typecheck, ESLint, backend plugin/SDK tests, Go
|
||||
lint, plugin UI tests (44), plugin Go race tests, vet, package verification, and public
|
||||
docs validation all passed.
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
id: "12i-shared-task-indicator-hover-summary"
|
||||
title: "Reuse the native pull-request summary from registered task indicators"
|
||||
status: completed
|
||||
wave: 3i
|
||||
depends_on: ["12h-native-create-unlink-indicators-saved-queries"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 12i: Reuse the Native Pull-Request Summary from Registered Task Indicators
|
||||
|
||||
## Root cause
|
||||
|
||||
`PRTaskIcon` renders GitHub's structured status summary, while
|
||||
`RegisteredChangeRequestTaskIcon` independently renders only the association count as
|
||||
tooltip text. The registered-provider path never subscribes to or lazily refreshes the
|
||||
provider's existing task review snapshot, so it cannot supply title/review/CI detail.
|
||||
|
||||
## Mobile design contract
|
||||
|
||||
- Desktop task switcher/Kanban/rich-list icons disclose the shared structured summary on
|
||||
mouse hover and keyboard focus.
|
||||
- The nearest mobile exemplar is the existing registered topbar/composer status drawer
|
||||
and mobile Review navigation. Those touch paths already expose the same normalized
|
||||
review data and remain the mobile entry point; the sidebar hover affordance is not
|
||||
mounted as a phone-only interaction.
|
||||
- Shared provider state and summary derivation remain viewport-neutral. No new scroll
|
||||
owner, safe-area surface, or touch-only control is introduced.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/web/components/{github,integrations}/**` shared task-summary presentation,
|
||||
registered task icon, and focused tests
|
||||
- `apps/web/e2e/tests/plugins/**` desktop hover contract and existing mobile parity path
|
||||
- `docs/{specs,plans,public}/**` provider contract documentation
|
||||
|
||||
## TDD and implementation
|
||||
|
||||
1. RED: prove a registered linked task's hover/focus tooltip lacks the PR number, title,
|
||||
review, and CI rows even when its provider publishes `ReviewItemSummary.taskStatus`.
|
||||
2. Extract/reuse the exact GitHub task-summary renderer as host-owned, provider-neutral
|
||||
presentation. Map normalized registered review status into that renderer.
|
||||
3. Subscribe to task review snapshots without refreshing every task row. Refresh only
|
||||
when the icon opens, using the existing deduplicated provider refresh lease.
|
||||
4. Preserve association-only initial rendering, registry unload cleanup, keyboard
|
||||
focus/Escape behavior, and semantic status color/count.
|
||||
5. Prove the real packaged Bitbucket provider in the isolated seed; retain the existing
|
||||
mobile status/Review E2E as the touch path.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Bitbucket's linked-task icon opens the same structured summary anatomy as GitHub.
|
||||
- The first workspace association refresh remains one bounded request across task rows;
|
||||
task detail is not fetched until hover/focus or another active review surface needs it.
|
||||
- Multiple linked PRs render separate summary entries; missing detail degrades to the
|
||||
existing accessible linked-count label while loading.
|
||||
- Provider unload removes the icon and cancels in-flight work.
|
||||
- Focused frontend tests, typecheck/lint, rendered desktop verification, existing mobile
|
||||
parity coverage, and `git diff --check` pass.
|
||||
|
||||
## Risks
|
||||
|
||||
- Mount-time use of the general review hook would reintroduce N-per-task provider calls;
|
||||
use subscriptions plus open-time refresh instead.
|
||||
- A hover tooltip has no touch equivalent; the existing mobile Status/Review path must
|
||||
remain discoverable and tested.
|
||||
|
||||
## Completion evidence
|
||||
|
||||
- Focused Vitest: 4 files / 16 tests passed.
|
||||
- Web typecheck and full ESLint passed.
|
||||
- Packaged Bitbucket plugin E2E proved association discovery stays detail-lazy until
|
||||
hover, then renders PR #42, title, Approved review, and Passed CI through the shared
|
||||
host summary.
|
||||
- Mobile plugin contract E2E passed on `mobile-chrome`, preserving the touch Review path.
|
||||
- The isolated seed rendered the correctly embedded production bundle and the same
|
||||
structured summary; `apps/web/.pr-assets/bitbucket-sidebar-pr-summary.png` records it.
|
||||
- Follow-up manual acceptance found the registered glyph remained hard-coded muted.
|
||||
Focused regression coverage now proves normalized provider detail drives the same
|
||||
host-owned semantic status colors as first-party pull requests; the muted association-
|
||||
only fallback remains until lazy detail arrives.
|
||||
- The packaged-provider desktop E2E now asserts the resolved semantic color, and the
|
||||
public plugin-authoring reference maps every code-host hook to its host-owned result
|
||||
with eight focused screenshots from an isolated packaged-plugin run.
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
id: "13-contract-e2e-release-marketplace"
|
||||
title: "Cross-repository contract E2E, release, and marketplace"
|
||||
status: in_progress
|
||||
wave: 4
|
||||
depends_on: ["03-protocol-manifest-actions", "04-frontend-plugin-registry", "05-dynamic-composer-reference-sources", "06-plugin-owned-task-lifecycle", "07-provider-neutral-git-credentials", "08-native-repository-provider", "09-native-link-review-surfaces", "10-cloud-dc-domain-auth", "11-plugin-workflows-watches", "12-plugin-ui-native-registrations", "12b-github-parity-page", "12c-exact-code-host-ui-parity", "12d-host-native-task-link-parity", "12h-native-create-unlink-indicators-saved-queries"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/bitbucket-plugin/spec.md"
|
||||
---
|
||||
|
||||
# Task 13: Cross-repository contract E2E, release, and marketplace
|
||||
|
||||
## Intent
|
||||
|
||||
Prove packaged host/plugin integration and publish only after every required capability
|
||||
and security contract passes. Marketplace registry is final mutation.
|
||||
|
||||
## Owned paths
|
||||
|
||||
- `apps/backend/cmd/plugin-fixture/`
|
||||
- `apps/backend/internal/plugins/runtime/testdata/fixtureplugin/main.go`
|
||||
- `apps/web/e2e/tests/plugins/bitbucket-plugin-contract.spec.ts`
|
||||
- `apps/web/e2e/tests/plugins/mobile-bitbucket-plugin-contract.spec.ts`
|
||||
- `plugin-registry/plugins.yaml`
|
||||
- `docs/public/plugins-authoring.md`
|
||||
- `docs/public/plugins-manifest.md`
|
||||
- `docs/public/plugins-marketplace.md`
|
||||
- `docs/public/integrations.md`
|
||||
- Attached `kdlbs/kandev-plugin-bitbucket` release/package/docs paths.
|
||||
|
||||
## Dependencies
|
||||
|
||||
Tasks 03 through 12, integrated.
|
||||
|
||||
## Acceptance
|
||||
|
||||
1. Desktop/mobile E2E covers install/enable, authenticated connection action,
|
||||
repository picker, PR import, **Link → Bitbucket Pull Request**, plugin native
|
||||
review, composer `#` selection/submission, watch-created task, unload/reload, and
|
||||
secret-free errors.
|
||||
2. Containers E2E proves real HTTPS clone/push through helper leases for host and
|
||||
remote executor paths. Packaged plugin installs against released minimum host
|
||||
version.
|
||||
3. A public plugin release with the mandatory internal checksums and no false signing
|
||||
or provenance claim precedes the final `plugin-registry/plugins.yaml` entry; public
|
||||
docs accurately describe setup, security, compatibility, and live `api_write`
|
||||
behavior.
|
||||
|
||||
## Verification
|
||||
|
||||
```sh
|
||||
make -C apps/backend test
|
||||
make -C apps/backend lint
|
||||
cd apps && pnpm --filter @kandev/web lint
|
||||
cd apps/web && pnpm run typecheck
|
||||
cd apps/web && pnpm e2e --grep "Bitbucket plugin contract"
|
||||
cd apps/web && pnpm e2e --grep "mobile Bitbucket plugin contract"
|
||||
cd apps/web && KANDEV_E2E_CONTAINERS=1 pnpm e2e --project=containers --grep "Bitbucket plugin contract"
|
||||
node --test plugin-registry/build-index.test.mjs
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
Marketplace publication before host release/package/container evidence breaks minimum-
|
||||
version compatibility guarantees. Treat every capability-matrix row and all secret
|
||||
leakage checks as release gates.
|
||||
|
||||
## Progress and remaining gates
|
||||
|
||||
- The packaged fixture passes the desktop and native-mobile host contract, including
|
||||
authenticated action dispatch, repository selection, native Link and review
|
||||
surfaces, `#` search with submit-time rejection, plugin-owned task provenance, and
|
||||
disable/re-enable cleanup. The layout-owned desktop review tab now adopts the
|
||||
registered provider's review title; the exact packaged Bitbucket contract passes
|
||||
against a freshly built host bundle.
|
||||
- Mobile review selection now persists provider-neutral review IDs. Exact selections
|
||||
from built-in topbar actions and plugin/built-in review choosers share one path; a
|
||||
two-MR GitLab regression E2E proves the selected review is not replaced by the
|
||||
provider's primary item.
|
||||
- Plugin unit/race/vet/build checks and host/all-platform package checksum verification
|
||||
pass. The real package installs active on an isolated current development host;
|
||||
unconfigured `connection.get`, repository, and pull-request actions return safe empty
|
||||
states; disable/re-enable revokes and restores its route; and its desktop/mobile
|
||||
workbench, mobile drawer target, and overflow checks pass.
|
||||
- The real plugin accepts the host's canonical `id`/`key` composer reference, derives
|
||||
repository and pull-request identity, rejects mismatched identities, and still
|
||||
live-fetches the PR before authorizing submission. A configured Cloud/Data Center
|
||||
cross-repository run still requires disposable provider credentials and fixtures.
|
||||
- The plugin repository now provides an opt-in, fail-fast `make e2e-live` runner for
|
||||
one configured product at a time. It installs the real package, saves the token
|
||||
connection through the authenticated host action, exercises health/repositories/
|
||||
branches/PR/review reads, optionally performs explicitly authorized comment,
|
||||
approve/unapprove, and decline mutations, then disconnects in cleanup. Its live
|
||||
Playwright config disables traces, screenshots, and video. Cloud API-token and OAuth
|
||||
authorization-code/PKCE acceptance passed on 2026-08-05 against the disposable
|
||||
`kdbls-kandev/kandev-plugin-live-test` repository. OAuth callback replay was rejected,
|
||||
and the credential remained healthy across plugin disable/re-enable. Data Center
|
||||
remains pending a disposable target.
|
||||
- The current Cloud package additionally passed host-native manual linking, exact-branch
|
||||
auto-link recovery, idempotent watch creation, persisted-provider branch selection,
|
||||
desktop/mobile native Review, and task-topbar CI status. Live 90-second polling tracked
|
||||
an actual build-status transition from successful to in-progress and back, and the
|
||||
disposable marker was restored to successful.
|
||||
- Public docs and the marketplace index baseline validate.
|
||||
- Container credential specs are present for Docker and SSH, but this workspace lacks
|
||||
`KANDEV_E2E_CREDENTIAL_BROKER_PUBLIC_BASE_URL`; both tests therefore skip rather than
|
||||
claiming real HTTPS clone/push evidence.
|
||||
- The release workflow's independent packaged-plugin runner still fails closed without
|
||||
`KANDEV_PLUGIN_E2E_URL`. The manifest intentionally omits `min_kandev_version` until
|
||||
these host contracts ship in a named release and the same package passes against
|
||||
that released host.
|
||||
- Signing is intentionally deferred by
|
||||
[ADR-2026-08-01-bitbucket-initial-release-remains-unsigned](../../decisions/2026-08-01-bitbucket-initial-release-remains-unsigned.md).
|
||||
The initial package uses mandatory internal checksums, remains visibly unsigned,
|
||||
and makes no cryptographic publisher-provenance claim. Signing is no longer a Task
|
||||
13 blocker; the unreleased host version and external live-test gates still are.
|
||||
@@ -45,7 +45,7 @@ spec: ../../specs/ui/message-queue-merge.md
|
||||
- Plan sections: `Frontend`.
|
||||
- Patterns to mirror: `removeEntry` in `use-queue.ts`, the Edit/Remove ghost
|
||||
buttons in `queued-ghost-message.tsx`, `handleRemove`/`handleSave` in
|
||||
`queued-ghost-list.tsx`, and the existing `queued-ghost-list.test.tsx` /
|
||||
`queued-ghost-list.tsx`, and the existing `queued-ghost-list.test.tsx` /
|
||||
`queued-ghost-message.test.tsx` harnesses.
|
||||
- Verify `IconArrowMerge` exists in the installed `@tabler/icons-react`
|
||||
(^3.36.1) before importing; otherwise use `IconArrowsJoin` or the closest
|
||||
|
||||
@@ -28,6 +28,7 @@ var Handshake = plugin.HandshakeConfig{
|
||||
```
|
||||
|
||||
Env kandev injects into the subprocess:
|
||||
|
||||
- `KANDEV_PLUGIN_DATA_DIR` — per-plugin writable dir (`~/.kandev/plugins/<id>/data`).
|
||||
|
||||
## 3. Proto (`apps/backend/proto/kandev/plugin/v1/plugin.proto`)
|
||||
@@ -41,6 +42,14 @@ import "google/protobuf/struct.proto";
|
||||
service Plugin {
|
||||
rpc DeliverEvent(Event) returns (EventAck);
|
||||
rpc HandleWebhook(WebhookRequest) returns (WebhookResponse);
|
||||
// Browser calls pass through host-authenticated declared actions only.
|
||||
rpc HandleAction(PluginActionRequest) returns (PluginActionResponse);
|
||||
// Manifest-owned dynamic composer reference source operations.
|
||||
rpc SearchEntityReferences(SearchEntityReferencesRequest) returns (SearchEntityReferencesResponse);
|
||||
rpc AuthorizeEntityReference(AuthorizeEntityReferenceRequest) returns (AuthorizeEntityReferenceResponse);
|
||||
// Optional provider-neutral credential resolver for declared repository providers.
|
||||
rpc ResolveGitCredential(ResolveGitCredentialRequest) returns (ResolveGitCredentialResponse);
|
||||
rpc GetGitCredentialBinding(GitCredentialBindingRequest) returns (GitCredentialBindingResponse);
|
||||
}
|
||||
|
||||
// Implemented by KANDEV (served back over the go-plugin broker).
|
||||
@@ -81,6 +90,7 @@ service Host {
|
||||
rpc ListWorkflows(ListWorkflowsRequest) returns (ListWorkflowsResponse);
|
||||
rpc ListWorkflowSteps(ListWorkflowStepsRequest) returns (ListWorkflowStepsResponse);
|
||||
rpc ListAgentProfiles(ListAgentProfilesRequest) returns (ListAgentProfilesResponse);
|
||||
rpc ListExecutorProfiles(ListExecutorProfilesRequest) returns (ListExecutorProfilesResponse);
|
||||
rpc ListRepositories(ListRepositoriesRequest) returns (ListRepositoriesResponse);
|
||||
rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse);
|
||||
rpc ListSessionCodeStats(ListSessionCodeStatsRequest) returns (ListSessionCodeStatsResponse);
|
||||
@@ -93,6 +103,8 @@ service Host {
|
||||
rpc CreateTask(CreateTaskRequest) returns (Task);
|
||||
rpc UpdateTask(UpdateTaskRequest) returns (Task);
|
||||
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
|
||||
rpc PreviewPluginOwnedTaskTree(PreviewPluginOwnedTaskTreeRequest) returns (PreviewPluginOwnedTaskTreeResponse);
|
||||
rpc DeletePluginOwnedTaskTree(DeletePluginOwnedTaskTreeRequest) returns (DeletePluginOwnedTaskTreeResponse);
|
||||
}
|
||||
|
||||
message Event {
|
||||
@@ -114,6 +126,39 @@ message WebhookRequest {
|
||||
}
|
||||
message WebhookResponse { int32 status = 1; map<string, string> headers = 2; bytes body = 3; }
|
||||
|
||||
// The host derives resources and actor after normal HTTP auth/authorization. Body is
|
||||
// untrusted JSON bounded by the manifest declaration; plugins must not infer authority
|
||||
// from it. Response headers are filtered by the host allowlist.
|
||||
message PluginActionRequest {
|
||||
string action_key = 1;
|
||||
VerifiedActionContext context = 2;
|
||||
bytes body = 3;
|
||||
}
|
||||
message VerifiedActionContext {
|
||||
string actor_id = 1;
|
||||
string workspace_id = 2;
|
||||
string task_id = 3;
|
||||
string repository_id = 4;
|
||||
string session_id = 5;
|
||||
string head_branch = 6;
|
||||
}
|
||||
// status=0 preserves legacy 200. Otherwise the host accepts 200..599 and
|
||||
// projects the status after filtering headers and enforcing the body limit.
|
||||
message PluginActionResponse { bytes body = 1; map<string, string> headers = 2; int32 status = 3; }
|
||||
|
||||
message SearchEntityReferencesRequest { string source = 1; string workspace_id = 2; string query = 3; int32 limit = 4; }
|
||||
message SearchEntityReferencesResponse { repeated EntityReferenceCandidate candidates = 1; }
|
||||
message EntityReferenceCandidate { string provider_local_id = 1; string title = 2; string url = 3; google.protobuf.Struct attributes = 4; }
|
||||
message AuthorizeEntityReferenceRequest { string source = 1; string workspace_id = 2; string purpose = 3; google.protobuf.Struct reference = 4; }
|
||||
message AuthorizeEntityReferenceResponse { bool allowed = 1; string reason = 2; }
|
||||
|
||||
// Scope is host-verified. The credential value is transient; it must never be written
|
||||
// into a host URL, task state, command argument, log, or executor environment.
|
||||
message ResolveGitCredentialRequest { string provider_id = 1; string workspace_id = 2; string task_id = 3; string session_id = 4; string repository_id = 5; string host = 6; string path = 7; }
|
||||
message ResolveGitCredentialResponse { string username = 1; string secret = 2; string expires_at = 3; }
|
||||
message GitCredentialBindingRequest { string provider_id = 1; string workspace_id = 2; string task_id = 3; string session_id = 4; string repository_id = 5; string host = 6; string path = 7; }
|
||||
message GitCredentialBindingResponse { string binding = 1; }
|
||||
|
||||
message GetStateRequest { string scope = 1; string scope_id = 2; string key = 3; }
|
||||
message GetStateResponse { bool found = 1; google.protobuf.Struct value = 2; }
|
||||
message SetStateRequest { string scope = 1; string scope_id = 2; string key = 3; google.protobuf.Struct value = 4; }
|
||||
@@ -145,6 +190,15 @@ Notes: scope ∈ instance|workspace|task|agent (empty scope_id for instance —
|
||||
matches the state store). The plugin never passes its own id; the Host service
|
||||
instance is bound to the plugin's record at spawn time.
|
||||
|
||||
`DeletePluginOwnedTaskTree` is partial-progress aware. A successful response
|
||||
carries every deleted task ID. If deletion stops after removing descendants,
|
||||
the non-OK status includes a `DeletePluginOwnedTaskTreeProgress` detail with
|
||||
those IDs. The Go SDK preserves them in the returned `([]string, error)` so a
|
||||
plugin can reconcile completed deletions before retrying idempotent cleanup;
|
||||
callers must not discard progress merely because the error is non-nil. An absent root
|
||||
is a successful no-op, so a retry after a completed or externally removed tree remains
|
||||
safe.
|
||||
|
||||
### 3a. Host data API (ADR 0043)
|
||||
|
||||
Read/write RPCs let plugins read and write kandev's own domain data —
|
||||
@@ -162,16 +216,17 @@ capability gating, and cross-cutting conventions. See ADR 0043
|
||||
**Readable resources.** Each read RPC requires `api_read:<resource>` in the
|
||||
plugin's manifest:
|
||||
|
||||
| RPC | Capability | Resource |
|
||||
|---|---|---|
|
||||
| `ListTasks` / `GetTask` | `api_read:tasks` | tasks |
|
||||
| `ListWorkspaces` | `api_read:workspaces` | workspaces |
|
||||
| `ListWorkflows` | `api_read:workflows` | workflows |
|
||||
| `ListWorkflowSteps` | `api_read:workflows` | workflows |
|
||||
| `ListAgentProfiles` | `api_read:agent_profiles` | agent_profiles |
|
||||
| `ListRepositories` | `api_read:repositories` | repositories |
|
||||
| `ListSessions` | `api_read:sessions` | sessions |
|
||||
| `ListSessionCodeStats` | `api_read:sessions` | sessions |
|
||||
| RPC | Capability | Resource |
|
||||
| ----------------------- | ---------------------------- | ----------------- |
|
||||
| `ListTasks` / `GetTask` | `api_read:tasks` | tasks |
|
||||
| `ListWorkspaces` | `api_read:workspaces` | workspaces |
|
||||
| `ListWorkflows` | `api_read:workflows` | workflows |
|
||||
| `ListWorkflowSteps` | `api_read:workflows` | workflows |
|
||||
| `ListAgentProfiles` | `api_read:agent_profiles` | agent_profiles |
|
||||
| `ListExecutorProfiles` | `api_read:executor_profiles` | executor_profiles |
|
||||
| `ListRepositories` | `api_read:repositories` | repositories |
|
||||
| `ListSessions` | `api_read:sessions` | sessions |
|
||||
| `ListSessionCodeStats` | `api_read:sessions` | sessions |
|
||||
|
||||
An undeclared capability returns gRPC `PermissionDenied` with message
|
||||
`capability 'api_read:tasks' not declared` (substituting the actual resource) —
|
||||
@@ -281,6 +336,11 @@ type Host interface { // injected before
|
||||
AgentProfiles() AgentProfileReader
|
||||
Repositories() RepositoryReader
|
||||
}
|
||||
// Optional Host extension, discovered without breaking existing Host implementations.
|
||||
type ExecutorProfileHost interface {
|
||||
ExecutorProfiles() ExecutorProfileReader
|
||||
}
|
||||
func ExecutorProfiles(host Host) (ExecutorProfileReader, bool)
|
||||
func Serve(p Plugin, opts ...Option) // blocks; wires go-plugin server + broker
|
||||
// Optional embeddable no-op base: sdk.UnimplementedPlugin
|
||||
// Optional embeddable no-op base for Host data accessors (every method
|
||||
@@ -288,6 +348,47 @@ func Serve(p Plugin, opts ...Option) // blocks; wires go-plugin server + bro
|
||||
// kandev side, not by plugin authors.
|
||||
```
|
||||
|
||||
### Provider extensions (additive)
|
||||
|
||||
`Plugin` remains source-compatible. `Serve` detects optional handler interfaces and
|
||||
returns `Unimplemented` only when a plugin has not opted into the corresponding
|
||||
manifest declaration:
|
||||
|
||||
```go
|
||||
type ActionHandler interface {
|
||||
HandleAction(context.Context, *PluginActionRequest) (*PluginActionResponse, error)
|
||||
}
|
||||
type EntityReferenceHandler interface {
|
||||
SearchEntityReferences(context.Context, *SearchEntityReferencesRequest) (*SearchEntityReferencesResponse, error)
|
||||
AuthorizeEntityReference(context.Context, *AuthorizeEntityReferenceRequest) (*AuthorizeEntityReferenceResponse, error)
|
||||
}
|
||||
type GitCredentialResolver interface {
|
||||
ResolveGitCredential(context.Context, *ResolveGitCredentialRequest) (*ResolveGitCredentialResponse, error)
|
||||
}
|
||||
type GitCredentialBinder interface {
|
||||
GetGitCredentialBinding(context.Context, *GitCredentialBindingRequest) (*GitCredentialBindingResponse, error)
|
||||
}
|
||||
```
|
||||
|
||||
`HandleAction` receives host-verified actor/resource context and bounded untrusted body
|
||||
separately. For task actions, an optional session selector is verified against the task;
|
||||
when paired with a verified repository selector, `head_branch` is resolved from that
|
||||
session's exact repository worktree. Browser body JSON cannot select or override it.
|
||||
`SearchEntityReferences` candidates are untrusted: the host injects
|
||||
descriptor identity and constructs canonical reference fields. `AuthorizeEntityReference`
|
||||
runs for search and submission. `ResolveGitCredential` receives an exact host-verified
|
||||
scope for both initial host materialization and helper-lease redemption, and returns
|
||||
only a transient credential consumed by the host Git process. Initial materialization
|
||||
and strict pre-worktree refresh carry the same task/session/repository scope; after a
|
||||
successful refresh the worktree layer uses local refs and performs no second network operation.
|
||||
Credential requests must include workspace, task, active session, repository, exact host, and exact path;
|
||||
an incomplete plugin-provider scope fails closed.
|
||||
`GetGitCredentialBinding` receives the same scope and returns an opaque, non-secret
|
||||
generation checked before and after redemption; missing or changed bindings fail closed.
|
||||
Disabling, failing, or uninstalling a plugin immediately revokes leases for all
|
||||
manifest-declared provider IDs. Repository host and path matching are exact and
|
||||
case-sensitive. The broker does not add, remove, or equate a trailing `.git`.
|
||||
|
||||
SDK types mirror proto but use `map[string]any` for Struct fields. The SDK owns
|
||||
all go-plugin/grpc plumbing (handshake, broker for Host, conversions).
|
||||
|
||||
@@ -325,6 +426,10 @@ type AgentProfileReader interface {
|
||||
List(ctx context.Context, page Page) ([]AgentProfile, *PageInfo, error)
|
||||
}
|
||||
|
||||
type ExecutorProfileReader interface {
|
||||
List(ctx context.Context, page Page) ([]ExecutorProfile, *PageInfo, error)
|
||||
}
|
||||
|
||||
type RepositoryReader interface {
|
||||
List(ctx context.Context, workspaceID string, page Page) ([]Repository, *PageInfo, error)
|
||||
}
|
||||
@@ -336,6 +441,16 @@ structs in `pluginsdk` (field-for-field mirrors of the proto messages, PascalCas
|
||||
Go names for the proto's snake_case fields, `*string` for `optional string`) —
|
||||
authors never see the generated `pluginv1.*` types.
|
||||
|
||||
`Repository` additionally carries credential-free provider origin identity:
|
||||
`source_type`, `provider_id`, `provider_repository_id`, `provider_host`, `provider_scope`,
|
||||
`owner_or_project`, `provider_name`, and `remote_url`. The Host never exposes a
|
||||
local checkout path, scripts, or credentials through this DTO.
|
||||
|
||||
`provider_scope` is opaque and credential-free. For provider-backed repositories,
|
||||
the strong identity is workspace + provider + scope + immutable provider repository
|
||||
ID. Host/name/owner fields remain routing and display metadata; scoped descriptors do
|
||||
not adopt legacy unscoped rows.
|
||||
|
||||
**Authoring example** — a plugin declaring `api_read: ["sessions"]` and reading
|
||||
computed per-session code stats instead of opening the kandev database:
|
||||
|
||||
@@ -378,8 +493,8 @@ the API, never the DB.
|
||||
converts the HTTP request to WebhookRequest and relays the WebhookResponse.
|
||||
- **Health**: go-plugin client `Ping()` every 30s (injectable), 3 consecutive
|
||||
failures → status `error` (+ restart attempt with backoff), recovery → `active`
|
||||
+ delivery flush. Crash (process exit) → immediate restart with backoff
|
||||
(max 5 attempts, then `error`).
|
||||
- delivery flush. Crash (process exit) → immediate restart with backoff
|
||||
(max 5 attempts, then `error`).
|
||||
- **Capability gating**: each Host RPC checks the plugin's manifest capabilities
|
||||
before doing any work — `state` for `GetState`/`SetState`/`DeleteState`/
|
||||
`ListState`, `secrets` for `RevealSecret`, `api_read:<resource>` for each Host
|
||||
@@ -410,7 +525,7 @@ runtime:
|
||||
linux-amd64: server/plugin-linux-amd64
|
||||
darwin-arm64: server/plugin-darwin-arm64
|
||||
# ... any subset
|
||||
min_kandev_version: "0.78.0" # optional
|
||||
min_kandev_version: "0.78.0" # optional
|
||||
```
|
||||
|
||||
Install pipeline: `POST /api/plugins/install` with JSON `{"url": "..."}` OR
|
||||
@@ -427,5 +542,13 @@ multipart field `package` → verify checksums.txt covers all files & hashes mat
|
||||
kandev **from the extracted package dir** (no reverse proxy, no upstream).
|
||||
- Management page: "Register plugin" (manifest paste) is replaced by "Install
|
||||
plugin" (URL input + file upload). No credentials are ever displayed.
|
||||
- Boot payload `plugins: [{id,name,bundleUrl,styleUrls}]` unchanged.
|
||||
- Boot payload `plugins: [{id,name,bundleUrl,styleUrls,repositoryProviderIds?}]`.
|
||||
`repositoryProviderIds` is JSON camelCase copied from manifest
|
||||
`repository_providers`; frontend loader records it before bundle initialization so
|
||||
provider/review registration can enforce declared ownership. Omission remains
|
||||
compatible with older payloads. Failed or timed-out initialization rolls back partial
|
||||
registrations and fences late callbacks from the expired activation attempt.
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
@@ -29,6 +29,7 @@ service HostData {
|
||||
rpc ListWorkflows(ListWorkflowsRequest) returns (ListWorkflowsResponse);
|
||||
rpc ListWorkflowSteps(ListWorkflowStepsRequest) returns (ListWorkflowStepsResponse);
|
||||
rpc ListAgentProfiles(ListAgentProfilesRequest) returns (ListAgentProfilesResponse);
|
||||
rpc ListExecutorProfiles(ListExecutorProfilesRequest) returns (ListExecutorProfilesResponse);
|
||||
rpc ListRepositories(ListRepositoriesRequest) returns (ListRepositoriesResponse);
|
||||
|
||||
// Sessions + code stats — capability api_read:sessions. Driven by a real
|
||||
@@ -41,10 +42,15 @@ service HostData {
|
||||
|
||||
// Writes — capability api_write:<resource>. Route through service methods so
|
||||
// the corresponding task.* events fire; this is the whole reason not to let
|
||||
// plugins write the DB.
|
||||
// plugins write the DB.
|
||||
// `ListExecutorProfiles` requires `api_read:executor_profiles`; preview/delete
|
||||
// capability is implicit in plugin-owned task provenance and is never conferred by
|
||||
// a task link stored in plugin state.
|
||||
rpc CreateTask(CreateTaskRequest) returns (CreateTaskResponse);
|
||||
rpc UpdateTask(UpdateTaskRequest) returns (UpdateTaskResponse);
|
||||
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
|
||||
rpc PreviewPluginOwnedTaskTree(PreviewPluginOwnedTaskTreeRequest) returns (PreviewPluginOwnedTaskTreeResponse);
|
||||
rpc DeletePluginOwnedTaskTree(DeletePluginOwnedTaskTreeRequest) returns (DeletePluginOwnedTaskTreeResponse);
|
||||
}
|
||||
|
||||
// ── Common ──────────────────────────────────────────────────────────────────
|
||||
@@ -86,6 +92,7 @@ message TaskRepository {
|
||||
string repository_id = 2;
|
||||
string base_branch = 3;
|
||||
int32 position = 4;
|
||||
string checkout_branch = 5;
|
||||
}
|
||||
|
||||
message TaskFilter {
|
||||
@@ -148,11 +155,31 @@ message AgentProfile {
|
||||
message ListAgentProfilesRequest { Page page = 1; }
|
||||
message ListAgentProfilesResponse { repeated AgentProfile profiles = 1; PageInfo page_info = 2; }
|
||||
|
||||
message ExecutorProfile {
|
||||
string id = 1;
|
||||
string display_name = 2;
|
||||
string executor_type = 3;
|
||||
}
|
||||
message ListExecutorProfilesRequest { Page page = 1; }
|
||||
message ListExecutorProfilesResponse { repeated ExecutorProfile profiles = 1; PageInfo page_info = 2; }
|
||||
|
||||
message Repository {
|
||||
string id = 1;
|
||||
string workspace_id = 2;
|
||||
string name = 3; // owner/repo slug when known, else name
|
||||
optional string default_branch = 4;
|
||||
// Credential-free provider origin identity. Never expose local paths,
|
||||
// scripts, or credentials through this Host DTO.
|
||||
string source_type = 5;
|
||||
string provider_id = 6;
|
||||
string provider_repository_id = 7;
|
||||
string provider_host = 8;
|
||||
string owner_or_project = 9;
|
||||
string provider_name = 10;
|
||||
string remote_url = 11;
|
||||
// Opaque provider-defined connection scope. Together with the immutable
|
||||
// provider_repository_id, this is the durable upstream identity.
|
||||
string provider_scope = 12;
|
||||
}
|
||||
message ListRepositoriesRequest { string workspace_id = 1; Page page = 2; }
|
||||
message ListRepositoriesResponse { repeated Repository repositories = 1; PageInfo page_info = 2; }
|
||||
@@ -204,6 +231,35 @@ message CreateTaskRequest {
|
||||
optional string parent_id = 6;
|
||||
bool start_agent = 7;
|
||||
// kandev stamps source = "plugin:<id>" server-side; not settable here.
|
||||
repeated PluginTaskRepository repositories = 8;
|
||||
optional PluginTaskLaunchOptions launch = 9;
|
||||
google.protobuf.Struct metadata = 10; // plugin namespace only; host reserves source.
|
||||
}
|
||||
message PluginTaskRepository {
|
||||
string repository_id = 1; // existing Kandev repository, or empty with remote below
|
||||
optional RemoteRepositoryDescriptor remote = 2;
|
||||
optional string base_branch = 3;
|
||||
optional string checkout_branch = 4;
|
||||
optional int64 pull_request_number = 5;
|
||||
}
|
||||
message RemoteRepositoryDescriptor {
|
||||
string provider_id = 1;
|
||||
string provider_host = 2;
|
||||
string owner_or_project = 3;
|
||||
string provider_repository_id = 4;
|
||||
string name = 5;
|
||||
string clone_url = 6; // exact credential-free URL; host never reconstructs it
|
||||
optional string default_branch = 7;
|
||||
optional string base_branch = 8;
|
||||
optional string head_branch = 9;
|
||||
optional int64 pull_request_number = 10;
|
||||
string provider_scope = 11; // credential-free configured provider instance
|
||||
}
|
||||
message PluginTaskLaunchOptions {
|
||||
optional string agent_profile_id = 1;
|
||||
optional string executor_profile_id = 2;
|
||||
optional string prompt = 3;
|
||||
optional string plan_mode = 4;
|
||||
}
|
||||
message CreateTaskResponse { Task task = 1; }
|
||||
message UpdateTaskRequest {
|
||||
@@ -228,3 +284,10 @@ message SendMessageResponse {
|
||||
string session_id = 1; // the session the message was delivered to
|
||||
string status = 2; // "queued" | "sent" | "started"
|
||||
}
|
||||
|
||||
// Deletion is owner-scoped. Host compares metadata.source with calling plugin ID; links
|
||||
// in plugin state are not deletion authority. Preview always precedes destructive UI.
|
||||
message PreviewPluginOwnedTaskTreeRequest { string root_task_id = 1; }
|
||||
message PreviewPluginOwnedTaskTreeResponse { repeated Task tasks = 1; }
|
||||
message DeletePluginOwnedTaskTreeRequest { string root_task_id = 1; }
|
||||
message DeletePluginOwnedTaskTreeResponse { repeated string deleted_task_ids = 1; }
|
||||
|
||||
@@ -6,7 +6,11 @@ diverge without updating this file.
|
||||
## Loading model
|
||||
|
||||
1. Backend boot payload gains `plugins: ActivePlugin[]` where
|
||||
`ActivePlugin = { id: string; name: string; bundleUrl: string; styleUrls?: string[] }`.
|
||||
`ActivePlugin = { id: string; name: string; bundleUrl: string; styleUrls?: string[];
|
||||
repositoryProviderIds?: string[] }`. `repositoryProviderIds` is JSON
|
||||
`repositoryProviderIds`, copied from manifest `repository_providers`. It is optional
|
||||
only for additive compatibility with older boot payloads; a present empty list means
|
||||
the plugin declared no repository providers.
|
||||
`bundleUrl` = `/api/plugins/{id}/bundle` — kandev serves this **directly from the
|
||||
extracted package directory** on local disk
|
||||
(`~/.kandev/plugins/<id>/<version>/ui/...`, per manifest `ui.bundle`). There is no
|
||||
@@ -14,7 +18,14 @@ diverge without updating this file.
|
||||
be running to serve the UI bundle, since installation already extracted the file.
|
||||
2. On SPA boot, the **plugin host** (`apps/web/lib/plugins/host.ts`) iterates
|
||||
`bootPayload.plugins`, injects any `styleUrls` as `<link>`, and dynamically
|
||||
`import(/* @vite-ignore */ bundleUrl)` each bundle as a native ES module.
|
||||
`import(/* @vite-ignore */ bundleUrl)` each bundle as a native ES module. Before a
|
||||
bundle can initialize, the loader supplies its `repositoryProviderIds` to the
|
||||
registry (for example `setDeclaredRepositoryProviderIds(pluginId, ids)`). The scoped
|
||||
registry then rejects `registerRepositoryProvider` or `registerReviewProvider` IDs
|
||||
outside that declared set. An omitted field preserves older-host compatibility;
|
||||
it does not invent provider ownership. Provider IDs are canonical lowercase
|
||||
identifiers: the manifest validator and frontend registry reject uppercase or
|
||||
otherwise non-canonical variants instead of creating case-dependent ownership.
|
||||
3. Each bundle, when evaluated, calls the global:
|
||||
```ts
|
||||
window.registerKandevPlugin(pluginId, {
|
||||
@@ -28,6 +39,12 @@ diverge without updating this file.
|
||||
initialization finishes. Slow or failed reloads do not by themselves revoke
|
||||
open or saved task panels. On explicit plugin disable/uninstall the host calls
|
||||
`destroy?.()`, removes the plugin's registrations, and closes its panels.
|
||||
Each initialization attempt is transactional: failure or timeout unregisters
|
||||
its partial contributions, aborts plugin-owned work, and fences callbacks from
|
||||
the expired generation. The same generation owns host-created subscriptions,
|
||||
modal and task-link handles, toasts, and review surfaces; the loader closes or
|
||||
unsubscribes them before calling `destroy` exactly once. Requests and callbacks
|
||||
from an expired generation cannot mutate the replacement generation.
|
||||
|
||||
## Global entry point
|
||||
|
||||
@@ -35,6 +52,12 @@ diverge without updating this file.
|
||||
host before any bundle loads. Bundles are authored with React as an **external**;
|
||||
they must use `host.React` (NOT bundle their own React) to share the host instance.
|
||||
|
||||
The independently consumable frontend type contract is the runtime-free
|
||||
`@kandev/plugin-sdk` package in `apps/packages/plugin-sdk`. Official plugins import
|
||||
these types instead of re-declaring this document or importing `apps/web` internals.
|
||||
The host has a compile-time assignability test, and the real Bitbucket package is a
|
||||
required exact-head compatibility consumer.
|
||||
|
||||
## `host: PluginHostApi`
|
||||
|
||||
```ts
|
||||
@@ -42,22 +65,58 @@ interface PluginHostApi {
|
||||
pluginId: string;
|
||||
React: typeof import("react"); // host React instance (shared)
|
||||
jsx: typeof React.createElement; // convenience alias (h)
|
||||
store: {
|
||||
// kandev app store (zustand StoreApi)
|
||||
getState(): AppState;
|
||||
setState(partial): void;
|
||||
subscribe(listener): () => void;
|
||||
context: {
|
||||
// Versioned provider-neutral reads; never exposes private AppState slices.
|
||||
getActiveWorkspaceId(): string | undefined;
|
||||
subscribeActiveWorkspace(listener): () => void;
|
||||
getTaskCreationContext(workspaceId: string): TaskCreationContext | null;
|
||||
subscribeTaskCreationContext(workspaceId: string, listener): () => void;
|
||||
resolveRepositoryId(identity: RepositoryIdentityInput): string | undefined;
|
||||
};
|
||||
// Compatibility only for older bundles. Deliberately absent from
|
||||
// @kandev/plugin-sdk; new/official plugins must use host.context.
|
||||
store: Pick<StoreApi<AppState>, "getState" | "setState" | "subscribe">;
|
||||
api: {
|
||||
// fetch scoped to this plugin's backend via kandev proxy:
|
||||
// GET/POST {method} /api/plugins/{id}/... ; returns parsed JSON
|
||||
// Low-level request scoped to this plugin's host path. It MUST NOT target a
|
||||
// public webhook path or be used for authenticated provider commands.
|
||||
fetch(path: string, init?: RequestInit): Promise<Response>;
|
||||
// Authenticated action declared in this plugin's manifest. The host verifies the
|
||||
// indicated resource and passes it to the plugin separately from body JSON. This
|
||||
// is the only browser-to-plugin command path; never call a public webhook route.
|
||||
invokeAction<TResponse>(
|
||||
key: string,
|
||||
input?: {
|
||||
workspaceId?: string;
|
||||
taskId?: string;
|
||||
sessionId?: string;
|
||||
repositoryId?: string;
|
||||
body?: unknown;
|
||||
},
|
||||
options?: { signal?: AbortSignal },
|
||||
): Promise<TResponse>;
|
||||
// Backend API origin ("" when SPA and API share an origin) — for reaching
|
||||
// first-party kandev REST endpoints without re-deriving the split-origin
|
||||
// dev/desktop base URL from window internals.
|
||||
baseUrl: string;
|
||||
};
|
||||
ui: Record<string, unknown>; // curated @kandev/ui components + app UI (see below)
|
||||
ui: PluginUIApi; // named curated host components; no open Record index
|
||||
// Plugin-scoped locale and translation API. Components use the reactive
|
||||
// hook; registry getters may use the imperative translator.
|
||||
i18n: {
|
||||
readonly locale: string;
|
||||
t(
|
||||
key: string,
|
||||
options?: {
|
||||
defaultValue?: string;
|
||||
count?: number;
|
||||
values?: Readonly<Record<string, string | number>>;
|
||||
},
|
||||
): string;
|
||||
useTranslation(): {
|
||||
readonly locale: string;
|
||||
t: PluginHostApi["i18n"]["t"];
|
||||
};
|
||||
};
|
||||
// The resolved light/dark theme, read live on every access. `host` is built
|
||||
// once per plugin load, so copying this into a variable that outlives a
|
||||
// render freezes it; read it during render, and pair it with onThemeChange
|
||||
@@ -73,9 +132,17 @@ interface PluginHostApi {
|
||||
// (e.g. /t/{taskId}) without a full reload.
|
||||
navigate(href: string, options?: { replace?: boolean }): void;
|
||||
// Imperatively opens a modal window rendered by the host's <PluginModalHost/>
|
||||
// (mounted once at the app root, isolated behind its own error boundary).
|
||||
// (mounted once at the app root with its own tooltip provider and isolated
|
||||
// behind its own error boundary).
|
||||
// Independent of keybindings — any plugin code path may call it.
|
||||
openModal(options: PluginModalOptions): PluginModalHandle;
|
||||
// Opens Kandev's native one-field task change-request linking workflow.
|
||||
// Provider code supplies copy, parsing, and mutation only; the host owns
|
||||
// validation placement, submitting state, footer, toast, and close behavior.
|
||||
openTaskLinkDialog(options: PluginTaskLinkDialogOptions): PluginModalHandle;
|
||||
// Opens a registered provider review in the native desktop dock panel or
|
||||
// current mobile session review. Plugins do not reach into host layout stores.
|
||||
openTaskReview(options: PluginTaskReviewOptions): void;
|
||||
// Sonner's imperative toast. The host mounts the single <Toaster/>, so
|
||||
// there is nothing to render and nothing to wire — and because it is
|
||||
// imperative rather than a component, it works from inside a plugin modal
|
||||
@@ -97,6 +164,8 @@ interface PluginStorageEntry {
|
||||
}
|
||||
|
||||
interface PluginStorageSetOptions {
|
||||
// Abort the request when the owning surface or plugin generation ends.
|
||||
signal?: AbortSignal;
|
||||
// Optimistic-concurrency guard: the updatedAt the caller last read. The
|
||||
// write is rejected (the returned promise rejects with a
|
||||
// PluginStorageConflictError) if the stored row was modified after this
|
||||
@@ -132,6 +201,7 @@ interface PluginStorageApi {
|
||||
scope: PluginStorageScope,
|
||||
scopeId: string,
|
||||
key: string,
|
||||
options?: { signal?: AbortSignal },
|
||||
): Promise<PluginStorageEntry | undefined>;
|
||||
set(
|
||||
scope: PluginStorageScope,
|
||||
@@ -144,12 +214,13 @@ interface PluginStorageApi {
|
||||
scope: PluginStorageScope,
|
||||
scopeId: string,
|
||||
key: string,
|
||||
options?: Pick<PluginStorageSetOptions, "writerId">,
|
||||
options?: Pick<PluginStorageSetOptions, "writerId" | "signal">,
|
||||
): Promise<void>;
|
||||
// Every entry under (scope, scopeId), ordered by key. Not paginated.
|
||||
list(
|
||||
scope: PluginStorageScope,
|
||||
scopeId: string,
|
||||
options?: { signal?: AbortSignal },
|
||||
): Promise<PluginStorageEntry[]>;
|
||||
// Subscribes to live updates for this plugin's own storage made from
|
||||
// another tab, device, or surface — e.g. the kanban Edit modal and the
|
||||
@@ -187,16 +258,56 @@ interface PluginUserStateChange {
|
||||
|
||||
interface PluginModalOptions {
|
||||
title?: string; // rendered in a DialogHeader/DialogTitle; omit for no header title
|
||||
description?: string; // rendered below the title in the host-owned header
|
||||
content: React.ComponentType<{ slotProps?: unknown }>; // reuses the slot-component contract
|
||||
size?: "sm" | "md" | "lg" | "xl"; // maps to the host's Dialog width classes; default "md"
|
||||
dismissible?: boolean; // overlay click / Escape close the modal; default true
|
||||
presentation?: "dialog" | "drawer"; // default dialog; use drawer for native phone actions
|
||||
}
|
||||
|
||||
interface PluginModalHandle {
|
||||
close(): void; // closes this modal instance; no-op if already closed
|
||||
}
|
||||
|
||||
interface PluginTaskLinkDialogOptions {
|
||||
title: string;
|
||||
description: string;
|
||||
inputLabel: string;
|
||||
placeholder?: string;
|
||||
emptyError: string;
|
||||
failureMessage: string;
|
||||
successMessage: string;
|
||||
inputTestId?: string;
|
||||
errorTestId?: string;
|
||||
submitTestId?: string;
|
||||
// The host aborts this signal when the user cancels or closes the dialog.
|
||||
onSubmit(reference: string, signal: AbortSignal): Promise<void>;
|
||||
}
|
||||
|
||||
interface PluginTaskReviewOptions {
|
||||
providerId: string;
|
||||
reviewKey: string;
|
||||
title?: string;
|
||||
presentation: "desktop" | "mobile";
|
||||
sessionId?: string;
|
||||
}
|
||||
```
|
||||
|
||||
For `host.api.invokeAction`, workspace-scoped actions accept only `workspaceId`;
|
||||
repository-scoped actions accept `workspaceId` plus `repositoryId`; task-scoped
|
||||
actions require `taskId`, may include a matching `workspaceId`, and may include
|
||||
`repositoryId` only when that persisted repository is attached to the verified task.
|
||||
A task action may also include `sessionId`; the host verifies it belongs to that task.
|
||||
When both session and repository selectors are present, the host resolves the exact
|
||||
non-empty worktree branch and exposes it only in the backend verified action context.
|
||||
Resource selectors never become part of the untrusted action body.
|
||||
|
||||
An action handler may return an HTTP status from 200 through 599; zero preserves the
|
||||
legacy 200 response. The host forwards only safe response headers (`Content-Type`,
|
||||
`Cache-Control`, `ETag`, and `Retry-After`). Invalid statuses become 502, while
|
||||
transport/runtime errors become 503 without exposing internal error text. Plugins
|
||||
should use explicit statuses only for safe domain outcomes that callers can act on.
|
||||
|
||||
`host.ui` contents: shadcn primitives (Accordion*, Alert*, Badge, Button,
|
||||
Card*, Checkbox, Collapsible*, Dialog*, DropdownMenu*, Empty*, Input, Kbd,
|
||||
KbdGroup, Label, Pagination*, Popover*, Progress, ScrollArea, Select*,
|
||||
@@ -206,16 +317,110 @@ Tooltip*, including `TooltipProvider`), the recharts wrappers (`ChartContainer`,
|
||||
`ChartStyle`), plus first-party app UI: `PageTopbar` (the kandev title bar, for
|
||||
routes that opt out of the default chrome and own their layout),
|
||||
`TaskCreateDialog` (kandev's real create-task modal, prefilled via
|
||||
`initialValues`), `Combobox` (the app's Command+Popover picker), and
|
||||
`RichTextEditor`/`RichTextReadOnly` (narrow wrappers over the Plan panel's
|
||||
tiptap markdown editor — see below). The authoritative list is
|
||||
`initialValues`), `Combobox` (the app's Command+Popover picker), and the
|
||||
provider-neutral code-host dashboard set: `ChangeRequestList`,
|
||||
`ChangeRequestRow`, `ChangeRequestDetail`, `IntegrationListToolbar`, `IntegrationScopeBar`,
|
||||
`IntegrationSaveQueryDialog`, `IntegrationRepositoryFilter`, `IntegrationCursorPagination`,
|
||||
`IntegrationStartTaskMenu`, `IntegrationIcon`, `IntegrationChangeRequestStatus`, and
|
||||
`TaskRowIndicator`. The authoritative list is
|
||||
`apps/web/lib/plugins/host-api.ts` (`PLUGIN_UI`).
|
||||
|
||||
In create mode, `TaskCreateDialog` accepts this optional transport seam:
|
||||
|
||||
```ts
|
||||
createTask?: (
|
||||
payload: Parameters<typeof createTask>[0],
|
||||
) => Promise<CreateTaskResponse>;
|
||||
```
|
||||
|
||||
When omitted, the dialog uses the normal `/api/v1/tasks` REST client. A trusted
|
||||
plugin wrapper may provide it to send the unchanged native payload through
|
||||
`Host Tasks.Create`; the same callback handles both the initial submission and
|
||||
the one allowed fresh-branch re-consent retry. Edit and session modes ignore it.
|
||||
The browser callback must not manufacture a repository-provider descriptor. It sends
|
||||
only native task choices plus an idempotency identifier to an authenticated plugin
|
||||
action; the plugin resolves repository identity from its live provider connection.
|
||||
Scope idempotency to one open dialog so retry does not create duplicates while a later
|
||||
intentional launch for the same change request still can.
|
||||
|
||||
Code-host plugins use that dashboard set as one contract. The plugin supplies
|
||||
normalized change-request data, filter state, task presets, and callbacks; the
|
||||
host owns row density, external-title behavior, responsive task menus,
|
||||
linked-task navigation, and loading/error/empty treatment. A row's sole workflow CTA
|
||||
is the shared **Task** preset menu, whose selection opens `TaskCreateDialog`
|
||||
directly. Review belongs to the registered task review-provider surface, not a
|
||||
parallel dashboard button or plugin-specific launch modal. `IntegrationIcon` maps
|
||||
semantic names (`pull-request`, `pull-request-closed`, `merged`, `filter`) to the same
|
||||
host Tabler glyphs used by first-party code-host pages; plugins do not copy their SVG
|
||||
paths. Runtime components stay in the Kandev host and are versioned with `host.ui`.
|
||||
A task preset may provide a semantic `iconName`; the host maps `eye`, `message`, and
|
||||
`tool` to the exact first-party **Review**, **Address feedback**, and **Fix CI** icons.
|
||||
`ReviewItemSummary.taskStatus` is the normal code-host status integration. Once a
|
||||
registered review provider publishes it, Kandev automatically mounts the exact shared
|
||||
topbar button, composer CI chip, desktop hover popover, and mobile drawer. Each rendered
|
||||
linked-task row acquires one deduplicated provider refresh so its indicator color is live
|
||||
before hover; hover/focus can refresh again, while active topbar/composer status refreshes
|
||||
every 90 seconds. Plugins must not register
|
||||
a visual slot or a second poller for these surfaces. Linked-task indicators also derive
|
||||
the same semantic color hierarchy from normalized state, review, and pipeline fields;
|
||||
providers do not send CSS classes or provider-specific color tokens. While the initial
|
||||
task detail request is pending, the indicator remains muted; publishing the snapshot
|
||||
updates both its summary and color. `IntegrationChangeRequestStatus` remains exposed for non-review-
|
||||
provider composition only.
|
||||
|
||||
`ChangeRequestDetail` is the exact provider-neutral detail component consumed by
|
||||
Kandev's GitHub panel. A review provider supplies its normalized model and advertised
|
||||
callbacks; Kandev owns header, branches, state/review badges, description, review/check/
|
||||
comment sections, add-to-context controls, scrolling, loading/error states, and native
|
||||
mobile sizing. Code-host plugins must use it instead of recreating the review page.
|
||||
A future SDK package may contain types or pure helpers, but not duplicate React/Radix
|
||||
runtime components.
|
||||
The curated surface also includes `RichTextEditor`/`RichTextReadOnly`, narrow
|
||||
wrappers over the Plan panel's tiptap markdown editor (see below).
|
||||
|
||||
Plugins must use these host instances — bundling copies of anything
|
||||
Radix/portal/context-based would split React context across instances and
|
||||
break refs/`asChild`. Pure-React libs (e.g. `@tabler/icons-react`) bundle
|
||||
fine.
|
||||
|
||||
### Persisted repository branch action
|
||||
|
||||
A manifest-owned repository provider that participates in Kandev's native task branch
|
||||
picker declares this standardized action:
|
||||
|
||||
```yaml
|
||||
actions:
|
||||
- key: "repositories.branches"
|
||||
scope: "workspace"
|
||||
max_body_bytes: 16384
|
||||
```
|
||||
|
||||
This action is invoked by the host backend, not the browser callback. Kandev resolves the
|
||||
active plugin that owns the repository's persisted provider ID and supplies a verified
|
||||
workspace context plus this snake-case body:
|
||||
|
||||
```json
|
||||
{
|
||||
"repository": {
|
||||
"provider_id": "example-provider",
|
||||
"provider_host": "https://code.example.com",
|
||||
"provider_scope": "https://code.example.com/context-a",
|
||||
"provider_repository_id": "owner/repository",
|
||||
"owner_or_project": "owner",
|
||||
"name": "repository",
|
||||
"clone_url": "https://code.example.com/owner/repository.git",
|
||||
"default_branch": "main"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Every field comes from the persisted workspace repository. The plugin returns
|
||||
`{"branches":[{"name":"main","commit":"optional","is_default":true}]}`. Kandev
|
||||
enforces the manifest request cap, a 15-second timeout, a 1 MiB response cap, at most
|
||||
10,000 branches, non-empty names, and name deduplication. Missing ownership, an inactive
|
||||
plugin, an undeclared/wrong-scope action, or malformed output fails closed. Providers
|
||||
must not require browser-supplied repository authority on this path.
|
||||
|
||||
The host wraps plugin routes, slots, and `openModal` content in a
|
||||
`TooltipProvider`, so a plain `Tooltip` works anywhere without one.
|
||||
`TooltipProvider` is exported for plugins that want their own
|
||||
@@ -261,6 +466,8 @@ interface PluginUtilsApi {
|
||||
// The host's clsx + tailwind-merge combiner, so class merging matches the
|
||||
// components it styles.
|
||||
cn(...inputs: unknown[]): string;
|
||||
// Non-security UUID with a fallback for supported insecure HTTP origins.
|
||||
generateUUID(): string;
|
||||
// Locale-aware relative time ("3 hours ago", "in 2 days", "yesterday") via
|
||||
// Intl.RelativeTimeFormat in the user's active locale; "" for unparseable
|
||||
// input. Prefer it over a hand-rolled ladder, which is English-only by
|
||||
@@ -269,7 +476,7 @@ interface PluginUtilsApi {
|
||||
}
|
||||
```
|
||||
|
||||
Both are functions, so they sit beside `navigate`/`openModal` rather than in
|
||||
These are functions, so they sit beside `navigate`/`openModal` rather than in
|
||||
`ui`, which is a component map.
|
||||
|
||||
### `host.ui.RichTextEditor` / `host.ui.RichTextReadOnly`
|
||||
@@ -349,17 +556,19 @@ own write).
|
||||
|
||||
```ts
|
||||
// icon: curated icon name (apps/web/lib/plugins/icons.ts — "ticket", "chart",
|
||||
// "robot", "database", ...); unknown/missing names render a puzzle glyph in
|
||||
// the sidebar.
|
||||
// "robot", "database", ...) or a plugin-owned component rendered with host
|
||||
// React. Unknown/missing names render a puzzle glyph in the sidebar.
|
||||
// section: "main" (default) renders as a top-level sidebar entry;
|
||||
// "integrations" renders inside the sidebar's Integrations section alongside
|
||||
// the first-party integration links (GitHub, Jira, ...). Hosts predating a
|
||||
// section value simply don't render items targeting it (additive change).
|
||||
type PluginIcon = string | React.ComponentType<{ className?: string }>;
|
||||
|
||||
interface NavItem {
|
||||
id: string;
|
||||
label: string;
|
||||
path: string;
|
||||
icon?: string;
|
||||
icon?: PluginIcon;
|
||||
section?: "main" | "settings" | "integrations";
|
||||
}
|
||||
|
||||
@@ -368,7 +577,7 @@ interface NavItem {
|
||||
interface PluginPageChrome {
|
||||
title?: string; // default: nav-item label for the same path, else plugin name
|
||||
subtitle?: string; // muted text next to the title
|
||||
icon?: string; // curated icon name; default: matching nav item's icon
|
||||
icon?: PluginIcon; // default: matching nav item's icon
|
||||
backHref?: string; // back-link target (host default "/")
|
||||
backLabel?: string; // back-link label (host default "Kandev")
|
||||
actions?: React.ComponentType; // rendered on the right side of the topbar
|
||||
@@ -381,6 +590,13 @@ interface PluginRouteOptions {
|
||||
}
|
||||
|
||||
interface PluginRegistry {
|
||||
// Installs flat locale catalogs under this plugin's isolated namespace.
|
||||
// English is required as the fallback. Registration is atomic; unload
|
||||
// removes all catalog bundles and locale changes invalidate host consumers.
|
||||
registerTranslations(
|
||||
catalogs: Readonly<Record<string, Readonly<Record<string, string>>>>,
|
||||
): void;
|
||||
|
||||
// Top-level SPA route, e.g. "/jira". Component rendered by the SPA route resolver
|
||||
// when window.location path === path (exact match; trailing segments via ":param" not
|
||||
// required for v1 — exact + startsWith("/plugins/{id}") allowed). The host wraps the
|
||||
@@ -402,9 +618,16 @@ interface PluginRegistry {
|
||||
// The settings shell already provides its own topbar chrome — no options here.
|
||||
registerSettingsRoute(path: string, Component: React.ComponentType): void;
|
||||
|
||||
// Native Settings > Integrations contribution. The host adds index/navigation
|
||||
// entries and wraps this component in the shared settings section.
|
||||
registerIntegrationSettings(
|
||||
registration: IntegrationSettingsRegistration,
|
||||
): void;
|
||||
|
||||
// Named slot injection. Host renders all components registered for a slot via
|
||||
// <PluginSlot name="..." slotProps={...}/>. Initial slots: "task-sidebar",
|
||||
// "settings-nav", "chat-input-actions", "chat-top-bar",
|
||||
// "settings-nav", "chat-input-actions", "task-create-input-actions",
|
||||
// "new-session-input-actions", "chat-top-bar",
|
||||
// "main-top-bar", "app-status-bar-left", "app-status-bar-right",
|
||||
// "plugin-settings", "task-card-indicators", and "task-card-tags".
|
||||
// "task-card-indicators" renders a small icon/badge beside the PR status
|
||||
@@ -417,9 +640,10 @@ interface PluginRegistry {
|
||||
// same `{ taskId: string, workspaceId: string | null, workflowStepId: string | null }`
|
||||
// shape as `slotProps` (`workspaceId` is null with no active workspace, and
|
||||
// `workflowStepId` is null when the task has no workflow step assigned).
|
||||
// "chat-input-actions" renders icon buttons in the chat composer toolbar
|
||||
// (beside the model picker, mic, and send) and forwards
|
||||
// `{ taskId, taskTitle, activeSessionId, sessionIds }` as `slotProps`.
|
||||
// "chat-input-actions", "task-create-input-actions", and
|
||||
// "new-session-input-actions" render composer actions for task/Quick Chat,
|
||||
// task creation, and new-session creation. Each forwards the typed
|
||||
// `PluginComposerSlotProps`, including native insert/focus/submit capabilities.
|
||||
// "chat-top-bar" renders status in the session top bar (beside the
|
||||
// document/editor/debug controls) and forwards
|
||||
// `{ taskId, taskTitle, workspaceId, activeSessionId, sessionIds }`. Both
|
||||
@@ -475,10 +699,21 @@ interface PluginRegistry {
|
||||
// the manifest validator and the frontend parser reject it.
|
||||
registerKeybinding(id: string, handler: (event: KeyboardEvent) => void): void;
|
||||
|
||||
// Contributes a panel to the task workspace "+" (add panel) menu (dockview
|
||||
// desktop) and, when mobileEnabled, the phone bottom nav. Panel identity
|
||||
// lives in the dockview params (pluginId/panelKey); the panel id is
|
||||
// `plugin:{pluginId}:{panelKey}`. See "Task panels" below.
|
||||
// Requires manifest ownership of provider.id. One active plugin owns one provider;
|
||||
// unload revokes it and aborts in-flight provider work. inspectURL returns a complete
|
||||
// credential-free HTTPS descriptor—host does not parse plugin provider URLs.
|
||||
registerRepositoryProvider(provider: RepositoryProviderRegistration): void;
|
||||
|
||||
// Native task-menu contribution. placement "link" renders in Link menus on desktop
|
||||
// and visible mobile action surfaces; host closes the menu before handler invocation.
|
||||
registerTaskAction(action: TaskActionRegistration): void;
|
||||
|
||||
// Native desktop/mobile review integration. Use external-store callbacks, never a
|
||||
// plugin hook, so enable/disable does not alter host hook ordering.
|
||||
registerReviewProvider(provider: ReviewProviderRegistration): void;
|
||||
|
||||
// Contributes a panel to the task workspace "+" menu and, when enabled,
|
||||
// the phone Panels picker.
|
||||
registerTaskPanel(registration: TaskPanelRegistration): void;
|
||||
|
||||
// Contributes an item to the kanban card's Edit submenu (group "edit") or
|
||||
@@ -492,6 +727,212 @@ interface PluginRegistry {
|
||||
registerTaskFilter(registration: TaskFilterRegistration): void;
|
||||
}
|
||||
|
||||
interface IntegrationSettingsRegistration {
|
||||
id: string;
|
||||
label: string;
|
||||
description: string;
|
||||
icon?: PluginIcon;
|
||||
Component: React.ComponentType<{ workspaceId?: string }>;
|
||||
}
|
||||
|
||||
// Integration settings render at /settings/integrations/{id} and
|
||||
// /settings/workspace/{workspaceId}/integrations/{id}. IDs are URL-safe, cannot
|
||||
// shadow first-party integrations, and have one active owner; unload revokes them.
|
||||
|
||||
interface RepositoryProviderRegistration {
|
||||
id: string;
|
||||
label: string;
|
||||
icon?: PluginIcon;
|
||||
listRepositories(context: {
|
||||
workspaceId: string;
|
||||
/** Optional server-side search text. */
|
||||
query?: string;
|
||||
/** Opaque cursor returned by this provider for the same query. */
|
||||
cursor?: string;
|
||||
/** Requested page size; a provider may return fewer items. */
|
||||
limit?: number;
|
||||
signal: AbortSignal;
|
||||
}): Promise<RepositoryInspection[] | RepositoryProviderPage>;
|
||||
// Optional synchronous performance hint. It never establishes ownership.
|
||||
matchesURL?(url: string): boolean;
|
||||
listBranches(context: {
|
||||
workspaceId: string;
|
||||
repository: RepositoryInspection;
|
||||
signal: AbortSignal;
|
||||
}): Promise<RepositoryProviderBranch[]>;
|
||||
inspectURL(context: {
|
||||
workspaceId: string;
|
||||
url: string;
|
||||
signal: AbortSignal;
|
||||
}): Promise<RepositoryInspection | null>;
|
||||
supportsDraft?: boolean; // default true; false hides the native draft option
|
||||
// Kandev pushes the verified checkout branch before invoking this callback.
|
||||
createChangeRequest?(context: {
|
||||
workspaceId: string;
|
||||
taskId: string;
|
||||
sessionId: string; // session whose checkout Kandev pushed
|
||||
repositoryId: string;
|
||||
repository: PluginHostRepository; // persisted host repository, not browser authority
|
||||
title: string;
|
||||
body: string;
|
||||
baseBranch?: string;
|
||||
draft: boolean;
|
||||
signal: AbortSignal;
|
||||
}): Promise<RepositoryChangeRequestCreateResult>;
|
||||
}
|
||||
|
||||
interface RepositoryProviderPage {
|
||||
repositories: RepositoryInspection[];
|
||||
nextCursor?: string;
|
||||
}
|
||||
|
||||
// The host binds every returned RepositoryInspection.providerId to the
|
||||
// registration's manifest-owned id; result data cannot spoof another namespace.
|
||||
// Legacy arrays remain valid. The host follows page cursors and rejects a cursor
|
||||
// repeated by a broken provider instead of looping forever.
|
||||
interface PluginHostRepository {
|
||||
id: string;
|
||||
workspace_id: string;
|
||||
name: string;
|
||||
provider: string;
|
||||
source_type?: string;
|
||||
provider_repo_id?: string;
|
||||
provider_host?: string;
|
||||
provider_scope?: string;
|
||||
provider_owner?: string;
|
||||
provider_name?: string;
|
||||
remote_url?: string;
|
||||
default_branch?: string;
|
||||
}
|
||||
interface RepositoryProviderBranch {
|
||||
name: string;
|
||||
}
|
||||
interface RepositoryChangeRequestCreateResult {
|
||||
url: string;
|
||||
provider?: string;
|
||||
output?: string;
|
||||
// False means remote creation succeeded but task association did not.
|
||||
linked?: boolean;
|
||||
// Safe detail shown with recovery guidance. Never retry remote creation.
|
||||
associationError?: string;
|
||||
}
|
||||
interface RepositoryInspection {
|
||||
providerId: string;
|
||||
providerHost: string;
|
||||
// Opaque, credential-free connection identity. Required when one authority
|
||||
// can host multiple independent provider roots.
|
||||
providerScope?: string;
|
||||
ownerOrProject: string;
|
||||
repositoryId: string;
|
||||
repositoryName: string;
|
||||
cloneUrl: string;
|
||||
defaultBranch?: string;
|
||||
baseBranch?: string;
|
||||
headBranch?: string;
|
||||
pullRequest?: { number: number; title: string };
|
||||
}
|
||||
interface TaskActionRegistration {
|
||||
id: string;
|
||||
label: string;
|
||||
icon?: PluginIcon;
|
||||
placement: "link";
|
||||
group?: string;
|
||||
visible?(context: PluginTaskActionContext): boolean;
|
||||
singleTaskOnly?: boolean;
|
||||
run(context: PluginTaskActionContext): Promise<void>;
|
||||
}
|
||||
interface PluginTaskActionContext {
|
||||
workspaceId: string;
|
||||
taskId: string;
|
||||
repositories: readonly PluginHostRepository[];
|
||||
pathname: string;
|
||||
presentation: "desktop" | "mobile";
|
||||
}
|
||||
interface ReviewProviderRegistration {
|
||||
id: string;
|
||||
label: string;
|
||||
icon?: PluginIcon;
|
||||
changeRequestNoun: string;
|
||||
order: number;
|
||||
getSnapshot(taskId: string): readonly ReviewItemSummary[];
|
||||
subscribe(taskId: string, listener: () => void): () => void;
|
||||
refresh(taskId: string, signal: AbortSignal): Promise<void>;
|
||||
// Implement all three association callbacks together. The host performs one
|
||||
// workspace-bounded association refresh and renders native task-list/card
|
||||
// indicators. Each rendered linked task leases refresh(taskId), deduplicated
|
||||
// with topbar/panel consumers; hover/focus may refresh it again.
|
||||
getAssociationSnapshot?(
|
||||
workspaceId: string,
|
||||
): readonly ReviewTaskAssociation[];
|
||||
subscribeAssociations?(workspaceId: string, listener: () => void): () => void;
|
||||
refreshAssociations?(workspaceId: string, signal: AbortSignal): Promise<void>;
|
||||
// Removes only this task link; it never deletes the remote change request.
|
||||
unlink?(context: {
|
||||
workspaceId: string;
|
||||
taskId: string;
|
||||
reviewKey: string;
|
||||
signal: AbortSignal;
|
||||
}): Promise<void>;
|
||||
ReviewPanel: React.ComponentType<PluginReviewPanelProps>;
|
||||
Selector?: React.ComponentType;
|
||||
EmptyState?: React.ComponentType;
|
||||
}
|
||||
interface ReviewTaskAssociation {
|
||||
providerId: string;
|
||||
taskId: string;
|
||||
reviewKey: string;
|
||||
connectionScope: string;
|
||||
repositoryId: string;
|
||||
changeRequestNumber: string | number;
|
||||
}
|
||||
interface ReviewItemSummary {
|
||||
providerId: string;
|
||||
reviewKey: string;
|
||||
title: string;
|
||||
url: string;
|
||||
connectionScope: string;
|
||||
repositoryId: string;
|
||||
changeRequestNumber: string | number;
|
||||
// open/opened/draft participates in native Create PR eligibility.
|
||||
state: string;
|
||||
statusBadge?: { label: string; tone?: string };
|
||||
taskStatus?: ReviewTaskStatus;
|
||||
}
|
||||
type ReviewTaskPipelineState = "success" | "failure" | "pending" | "neutral";
|
||||
interface ReviewTaskStatus {
|
||||
number: number | string;
|
||||
state: "open" | "merged" | "closed" | "draft";
|
||||
pipelineState: ReviewTaskPipelineState;
|
||||
checks: readonly {
|
||||
id: string;
|
||||
label: string;
|
||||
state: ReviewTaskPipelineState;
|
||||
detail?: string;
|
||||
url?: string;
|
||||
}[];
|
||||
review?: {
|
||||
state: "approved" | "changes_requested" | "pending";
|
||||
approved: number;
|
||||
required?: number;
|
||||
requested?: number;
|
||||
};
|
||||
unresolvedComments?: number;
|
||||
loading?: boolean;
|
||||
error?: string;
|
||||
updatedAt?: number;
|
||||
}
|
||||
interface PluginReviewPanelProps {
|
||||
panelId: string;
|
||||
presentation: "desktop" | "mobile";
|
||||
workspaceId: string;
|
||||
taskId: string;
|
||||
sessionId?: string;
|
||||
reviewKey: string;
|
||||
connectionScope: string;
|
||||
repositoryId: string;
|
||||
changeRequestNumber: string | number;
|
||||
}
|
||||
|
||||
type PluginPresentation = "desktop" | "mobile";
|
||||
|
||||
type PluginComposerSurface =
|
||||
@@ -530,7 +971,7 @@ interface PluginTaskPanelProps {
|
||||
interface TaskPanelRegistration {
|
||||
id: string; // plugin-local panel id (unique within the plugin, not globally)
|
||||
title: string; // add-panel-menu row label and dockview tab title
|
||||
icon?: string; // curated icon name (apps/web/lib/plugins/icons.ts)
|
||||
icon?: PluginIcon;
|
||||
Component: React.ComponentType<PluginTaskPanelProps>; // wrapped in a PluginErrorBoundary
|
||||
mobileEnabled?: boolean; // include in the phone's grouped Panels picker. Default: false.
|
||||
}
|
||||
@@ -575,6 +1016,11 @@ interface TaskFilterRegistration {
|
||||
}
|
||||
```
|
||||
|
||||
The host treats `matchesURL` only as a coarse candidate filter. It runs every
|
||||
remaining provider's cancellable, workspace-scoped `inspectURL`; `null` means the
|
||||
configured provider does not own the URL. One structured result wins, more than one
|
||||
is an ambiguity error, and registration order never decides ownership.
|
||||
|
||||
### App-status-bar slots
|
||||
|
||||
`app-status-bar-left` and `app-status-bar-right` are live named component slots.
|
||||
@@ -597,7 +1043,8 @@ interface AppStatusBarSlotProps {
|
||||
`placement` matches registration slot. `presentation` identifies the mounted host;
|
||||
the host mounts only one presentation at once. `density` is `full` on desktop and
|
||||
phone drawer, `compact` on tablet. `pathname` and active IDs are current-context
|
||||
hints, not entity payloads; read complete records from `host.store`.
|
||||
hints, not entity payloads. Use a typed `host.context` read or host-verified action;
|
||||
do not inspect private store slices from a released plugin.
|
||||
|
||||
Before customization, registration order is render order within each default side.
|
||||
Users can Cmd-drag on macOS or Ctrl-drag elsewhere with a mouse to move any item
|
||||
@@ -709,6 +1156,13 @@ and `getTaskMenuActions(group?)`. `unregisterWsHandler(pluginId, action, handler
|
||||
removes exactly one WS handler (used by `host.storage.subscribe`'s returned
|
||||
unsubscribe) without disturbing the plugin's other registrations.
|
||||
|
||||
Before `initialize`, the loader records `ActivePlugin.repositoryProviderIds` for the
|
||||
plugin ID. A present declaration is an allowlist for provider/review registration; an
|
||||
absent declaration is tolerated only for older payload compatibility. Disable/unload
|
||||
removes this declaration with the plugin's registrations. Failed/timed-out activation
|
||||
performs the same cleanup and an attempt token prevents late async registrations from
|
||||
reappearing.
|
||||
|
||||
Plugin top-level routes render inside `PluginPageFrame`
|
||||
(`apps/web/components/plugins/plugin-page.tsx`): a `PageTopbar` title bar above
|
||||
a scrollable content area, resolved from `options.topbar` with derived
|
||||
@@ -768,8 +1222,9 @@ Plugin JS runs in the kandev origin with store access — this is the accepted
|
||||
tradeoff of option C. v1 mitigations: only **active, operator-installed** plugins
|
||||
load; bundles are served by kandev from the extracted package directory (same-origin,
|
||||
no third-party CDN, no upstream network hop); host wraps `initialize` in try/catch so
|
||||
a broken plugin can't crash boot; registrations namespaced + bulk-revocable per
|
||||
plugin. No credentials are ever displayed to the operator — installing a plugin (via
|
||||
a broken plugin can't crash boot; failed/timed-out activation is rolled back; and
|
||||
registrations are namespaced + bulk-revocable per plugin. No credentials are ever
|
||||
displayed to the operator — installing a plugin (via
|
||||
URL or upload) has nothing to copy or reveal, unlike the old register flow's one-time
|
||||
API key/webhook secret. Sandboxing plugin JS (worker/realms) is explicit future work.
|
||||
|
||||
|
||||
|
After Width: | Height: | Size: 117 KiB |
|
After Width: | Height: | Size: 120 KiB |
|
After Width: | Height: | Size: 154 KiB |
|
After Width: | Height: | Size: 19 KiB |
@@ -6,24 +6,45 @@
|
||||
"audiences": ["user", "operator"],
|
||||
"stability": "stable",
|
||||
"docs": ["index", "use-kandev", "cli", "desktop-app", "run-as-a-service"],
|
||||
"sources": ["apps/cli/bin/native-shim.js", "apps/backend/internal/launcher/launcher.go", "apps/desktop/src-tauri/src/lib.rs"],
|
||||
"tests": ["apps/cli/bin/native-shim.test.mjs", "apps/desktop/e2e/desktop-launch-smoke.test.mjs"]
|
||||
"sources": [
|
||||
"apps/cli/bin/native-shim.js",
|
||||
"apps/backend/internal/launcher/launcher.go",
|
||||
"apps/desktop/src-tauri/src/lib.rs"
|
||||
],
|
||||
"tests": [
|
||||
"apps/cli/bin/native-shim.test.mjs",
|
||||
"apps/desktop/e2e/desktop-launch-smoke.test.mjs"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "backend-configuration",
|
||||
"audiences": ["operator", "contributor"],
|
||||
"stability": "stable",
|
||||
"docs": ["configuration", "operations", "cli"],
|
||||
"sources": ["apps/backend/internal/common/config/config.go", "apps/backend/internal/agentctl/server/config/config.go", "apps/backend/internal/profiles/profiles.go"],
|
||||
"tests": ["apps/backend/internal/common/config/config_test.go", "apps/backend/internal/agentctl/server/config/config_test.go", "apps/backend/internal/profiles/profiles_test.go"]
|
||||
"sources": [
|
||||
"apps/backend/internal/common/config/config.go",
|
||||
"apps/backend/internal/agentctl/server/config/config.go",
|
||||
"apps/backend/internal/profiles/profiles.go"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/common/config/config_test.go",
|
||||
"apps/backend/internal/agentctl/server/config/config_test.go",
|
||||
"apps/backend/internal/profiles/profiles_test.go"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "workspaces-and-repositories",
|
||||
"audiences": ["user"],
|
||||
"stability": "stable",
|
||||
"docs": ["use-kandev", "tasks-and-workflows", "configuration"],
|
||||
"sources": ["apps/backend/internal/task/handlers/workspace_handlers.go", "apps/web/components/app-sidebar/app-sidebar-workspace-picker.tsx"],
|
||||
"tests": ["apps/backend/internal/task/handlers/workspace_handlers_test.go", "apps/web/components/app-sidebar/app-sidebar-workspace-picker.test.tsx"],
|
||||
"sources": [
|
||||
"apps/backend/internal/task/handlers/workspace_handlers.go",
|
||||
"apps/web/components/app-sidebar/app-sidebar-workspace-picker.tsx"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/task/handlers/workspace_handlers_test.go",
|
||||
"apps/web/components/app-sidebar/app-sidebar-workspace-picker.test.tsx"
|
||||
],
|
||||
"settingsRoutes": ["/settings/workspace", "/settings/workspaces"],
|
||||
"mcpTools": ["list_repositories_kandev", "list_workspaces_kandev"]
|
||||
},
|
||||
@@ -31,9 +52,20 @@
|
||||
"id": "tasks-and-workflows",
|
||||
"audiences": ["user"],
|
||||
"stability": "stable",
|
||||
"docs": ["tasks-and-workflows", "workflow-tips", "workflow-import-export", "workflow-sync"],
|
||||
"sources": ["apps/backend/internal/orchestrator/workflow_store.go", "apps/web/components/kanban-with-preview.tsx"],
|
||||
"tests": ["apps/backend/internal/orchestrator/workflow_store_test.go", "apps/web/components/kanban-with-preview.test.ts"],
|
||||
"docs": [
|
||||
"tasks-and-workflows",
|
||||
"workflow-tips",
|
||||
"workflow-import-export",
|
||||
"workflow-sync"
|
||||
],
|
||||
"sources": [
|
||||
"apps/backend/internal/orchestrator/workflow_store.go",
|
||||
"apps/web/components/kanban-with-preview.tsx"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/orchestrator/workflow_store_test.go",
|
||||
"apps/web/components/kanban-with-preview.test.ts"
|
||||
],
|
||||
"mcpTools": [
|
||||
"create_workflow_kandev",
|
||||
"create_workflow_step_kandev",
|
||||
@@ -92,9 +124,22 @@
|
||||
"id": "sessions-and-coordination",
|
||||
"audiences": ["user"],
|
||||
"stability": "stable",
|
||||
"docs": ["sessions-and-review", "coordination", "automation-and-mcp", "agent-communication"],
|
||||
"sources": ["apps/backend/internal/mcp/handlers/spawn_session.go", "apps/backend/internal/mcp/handlers/parent_question.go", "apps/web/components/task/dockview-session-tabs.ts"],
|
||||
"tests": ["apps/backend/internal/mcp/handlers/spawn_session_test.go", "apps/backend/internal/mcp/handlers/parent_question_test.go", "apps/web/components/task/dockview-session-tabs.test.ts"],
|
||||
"docs": [
|
||||
"sessions-and-review",
|
||||
"coordination",
|
||||
"automation-and-mcp",
|
||||
"agent-communication"
|
||||
],
|
||||
"sources": [
|
||||
"apps/backend/internal/mcp/handlers/spawn_session.go",
|
||||
"apps/backend/internal/mcp/handlers/parent_question.go",
|
||||
"apps/web/components/task/dockview-session-tabs.ts"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/mcp/handlers/spawn_session_test.go",
|
||||
"apps/backend/internal/mcp/handlers/parent_question_test.go",
|
||||
"apps/web/components/task/dockview-session-tabs.test.ts"
|
||||
],
|
||||
"mcpTools": [
|
||||
"ask_parent_question_kandev",
|
||||
"ask_user_question_kandev",
|
||||
@@ -209,8 +254,14 @@
|
||||
"audiences": ["user", "operator"],
|
||||
"stability": "stable",
|
||||
"docs": ["executors", "remote-cloud-environment", "docker", "k8s"],
|
||||
"sources": ["apps/backend/internal/agent/executor/executor.go", "apps/web/app/settings/executors/page.tsx"],
|
||||
"tests": ["apps/web/e2e/tests/docker/docker-launch.spec.ts", "apps/web/e2e/tests/ssh/executor-crud.spec.ts"],
|
||||
"sources": [
|
||||
"apps/backend/internal/agent/executor/executor.go",
|
||||
"apps/web/app/settings/executors/page.tsx"
|
||||
],
|
||||
"tests": [
|
||||
"apps/web/e2e/tests/docker/docker-launch.spec.ts",
|
||||
"apps/web/e2e/tests/ssh/executor-crud.spec.ts"
|
||||
],
|
||||
"settingsRoutes": ["/settings/executor/new", "/settings/executors"],
|
||||
"mcpTools": [
|
||||
"create_executor_profile_kandev",
|
||||
@@ -225,8 +276,26 @@
|
||||
"audiences": ["user", "operator"],
|
||||
"stability": "stable",
|
||||
"docs": ["integrations", "configuration"],
|
||||
"sources": ["apps/web/components/app-sidebar/sections/integrations-section.tsx", "apps/backend/internal/integrations/workspacescope/workspacescope.go", "apps/backend/internal/azuredevops/service.go", "apps/web/app/azure-devops/azure-devops-page-client.tsx", "apps/backend/internal/github/app_registration_lifecycle_service.go", "apps/backend/internal/github/app_registration_import.go", "apps/web/lib/api/domains/github-auth-api.ts", "apps/backend/internal/mcp/server/server.go"],
|
||||
"tests": ["apps/web/components/app-sidebar/sections/integrations-section.test.tsx", "apps/backend/internal/integrations/workspacescope/workspacescope_test.go", "apps/backend/internal/azuredevops/service_test.go", "apps/web/e2e/tests/integrations/azure-devops.spec.ts", "apps/backend/internal/github/controller_app_registration_test.go", "apps/backend/internal/github/app_registration_import_test.go", "apps/web/e2e/tests/settings/github-app-registration.spec.ts", "apps/backend/internal/mcp/server/handlers_test.go"],
|
||||
"sources": [
|
||||
"apps/web/components/app-sidebar/sections/integrations-section.tsx",
|
||||
"apps/backend/internal/integrations/workspacescope/workspacescope.go",
|
||||
"apps/backend/internal/azuredevops/service.go",
|
||||
"apps/web/app/azure-devops/azure-devops-page-client.tsx",
|
||||
"apps/backend/internal/github/app_registration_lifecycle_service.go",
|
||||
"apps/backend/internal/github/app_registration_import.go",
|
||||
"apps/web/lib/api/domains/github-auth-api.ts",
|
||||
"apps/backend/internal/mcp/server/server.go"
|
||||
],
|
||||
"tests": [
|
||||
"apps/web/components/app-sidebar/sections/integrations-section.test.tsx",
|
||||
"apps/backend/internal/integrations/workspacescope/workspacescope_test.go",
|
||||
"apps/backend/internal/azuredevops/service_test.go",
|
||||
"apps/web/e2e/tests/integrations/azure-devops.spec.ts",
|
||||
"apps/backend/internal/github/controller_app_registration_test.go",
|
||||
"apps/backend/internal/github/app_registration_import_test.go",
|
||||
"apps/web/e2e/tests/settings/github-app-registration.spec.ts",
|
||||
"apps/backend/internal/mcp/server/handlers_test.go"
|
||||
],
|
||||
"settingsRoutes": [
|
||||
"/settings/integrations",
|
||||
"/settings/integrations/azure-devops",
|
||||
@@ -248,8 +317,14 @@
|
||||
"audiences": ["user", "operator"],
|
||||
"stability": "stable",
|
||||
"docs": ["automation-and-mcp", "integrations", "workflow-tips"],
|
||||
"sources": ["apps/backend/internal/automation/service.go", "apps/backend/internal/mcp/server/server.go"],
|
||||
"tests": ["apps/backend/internal/automation/service_test.go", "apps/backend/internal/mcp/server/server_test.go"],
|
||||
"sources": [
|
||||
"apps/backend/internal/automation/service.go",
|
||||
"apps/backend/internal/mcp/server/server.go"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/automation/service_test.go",
|
||||
"apps/backend/internal/mcp/server/server_test.go"
|
||||
],
|
||||
"settingsRoutes": ["/settings/automations", "/settings/external-mcp"],
|
||||
"mcpTools": ["get_mcp_config_kandev", "update_mcp_config_kandev"]
|
||||
},
|
||||
@@ -257,9 +332,25 @@
|
||||
"id": "personal-settings-and-secrets",
|
||||
"audiences": ["user"],
|
||||
"stability": "stable",
|
||||
"docs": ["security", "configuration", "developer-tools", "operations", "sessions-and-review"],
|
||||
"sources": ["apps/web/src/settings-routes.tsx", "apps/web/components/settings/settings-index.tsx", "apps/web/components/settings/general-settings.tsx", "apps/web/components/settings/layouts/layout-settings.tsx"],
|
||||
"tests": ["apps/web/src/settings-routes.test.ts", "apps/web/components/settings/settings-index.test.tsx", "apps/web/components/settings/terminal-settings.test.ts", "apps/web/lib/layout/layout-profiles.test.ts"],
|
||||
"docs": [
|
||||
"security",
|
||||
"configuration",
|
||||
"developer-tools",
|
||||
"operations",
|
||||
"sessions-and-review"
|
||||
],
|
||||
"sources": [
|
||||
"apps/web/src/settings-routes.tsx",
|
||||
"apps/web/components/settings/settings-index.tsx",
|
||||
"apps/web/components/settings/general-settings.tsx",
|
||||
"apps/web/components/settings/layouts/layout-settings.tsx"
|
||||
],
|
||||
"tests": [
|
||||
"apps/web/src/settings-routes.test.ts",
|
||||
"apps/web/components/settings/settings-index.test.tsx",
|
||||
"apps/web/components/settings/terminal-settings.test.ts",
|
||||
"apps/web/lib/layout/layout-profiles.test.ts"
|
||||
],
|
||||
"settingsRoutes": [
|
||||
"/settings",
|
||||
"/settings/preferences",
|
||||
@@ -286,18 +377,44 @@
|
||||
"id": "security-and-trust",
|
||||
"audiences": ["user", "operator"],
|
||||
"stability": "stable",
|
||||
"docs": ["security", "configuration", "executors", "automation-and-mcp", "operations"],
|
||||
"sources": ["apps/backend/internal/backendapp/middleware.go", "apps/backend/internal/gateway/websocket/origin.go", "apps/backend/internal/secrets/crypto.go"],
|
||||
"tests": ["apps/backend/internal/backendapp/middleware_test.go", "apps/backend/internal/gateway/websocket/origin_test.go"]
|
||||
"docs": [
|
||||
"security",
|
||||
"configuration",
|
||||
"executors",
|
||||
"automation-and-mcp",
|
||||
"operations"
|
||||
],
|
||||
"sources": [
|
||||
"apps/backend/internal/backendapp/middleware.go",
|
||||
"apps/backend/internal/gateway/websocket/origin.go",
|
||||
"apps/backend/internal/secrets/crypto.go"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/backendapp/middleware_test.go",
|
||||
"apps/backend/internal/gateway/websocket/origin_test.go"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "authentication-and-access",
|
||||
"audiences": ["user", "operator"],
|
||||
"stability": "beta",
|
||||
"docs": ["authentication"],
|
||||
"sources": ["apps/backend/internal/auth/httpmw/middleware.go", "apps/backend/internal/auth/service.go", "apps/backend/internal/auth/httpapi/handlers.go", "apps/web/components/app-sidebar/current-user-chip.tsx"],
|
||||
"tests": ["apps/backend/internal/auth/httpapi/handlers_test.go", "apps/backend/internal/auth/httpmw/middleware_test.go", "apps/web/lib/state/slices/auth/auth-slice.test.ts"],
|
||||
"settingsRoutes": ["/settings/system/users", "/settings/account/security", "/settings/account/tokens"]
|
||||
"sources": [
|
||||
"apps/backend/internal/auth/httpmw/middleware.go",
|
||||
"apps/backend/internal/auth/service.go",
|
||||
"apps/backend/internal/auth/httpapi/handlers.go",
|
||||
"apps/web/components/app-sidebar/current-user-chip.tsx"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/auth/httpapi/handlers_test.go",
|
||||
"apps/backend/internal/auth/httpmw/middleware_test.go",
|
||||
"apps/web/lib/state/slices/auth/auth-slice.test.ts"
|
||||
],
|
||||
"settingsRoutes": [
|
||||
"/settings/system/users",
|
||||
"/settings/account/security",
|
||||
"/settings/account/tokens"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "system-health-and-maintenance",
|
||||
@@ -343,7 +460,13 @@
|
||||
"id": "deployment-and-platforms",
|
||||
"audiences": ["operator"],
|
||||
"stability": "stable",
|
||||
"docs": ["docker", "k8s", "run-as-a-service", "windows-support", "operations"],
|
||||
"docs": [
|
||||
"docker",
|
||||
"k8s",
|
||||
"run-as-a-service",
|
||||
"windows-support",
|
||||
"operations"
|
||||
],
|
||||
"sources": ["Dockerfile", "apps/backend/internal/launcher/service.go"],
|
||||
"tests": ["apps/web/e2e/tests/docker/docker-launch.spec.ts"]
|
||||
},
|
||||
@@ -352,52 +475,113 @@
|
||||
"audiences": ["user", "operator"],
|
||||
"stability": "experimental",
|
||||
"docs": ["coordination", "feature-status", "office-provider-routing"],
|
||||
"sources": ["apps/backend/internal/office/routes.go", "apps/web/src/office-routes.tsx"],
|
||||
"tests": ["apps/backend/internal/office/onboarding/service_test.go", "apps/web/src/office-routes.test.ts"]
|
||||
"sources": [
|
||||
"apps/backend/internal/office/routes.go",
|
||||
"apps/web/src/office-routes.tsx"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/office/onboarding/service_test.go",
|
||||
"apps/web/src/office-routes.test.ts"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "plugin-system",
|
||||
"audiences": ["operator", "contributor"],
|
||||
"stability": "experimental",
|
||||
"docs": ["plugins", "plugins-authoring", "plugins-manifest"],
|
||||
"sources": ["apps/backend/internal/plugins/handlers.go", "apps/backend/pkg/pluginsdk/host.go", "apps/web/lib/plugins/host-api.ts"],
|
||||
"tests": ["apps/backend/internal/plugins/service_test.go", "apps/backend/internal/plugins/manifest/manifest_test.go", "apps/web/lib/plugins/host-api.test.ts"]
|
||||
"sources": [
|
||||
"apps/backend/internal/plugins/handlers.go",
|
||||
"apps/backend/pkg/pluginsdk/host.go",
|
||||
"apps/web/lib/plugins/host-api.ts"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/plugins/service_test.go",
|
||||
"apps/backend/internal/plugins/manifest/manifest_test.go",
|
||||
"apps/web/lib/plugins/host-api.test.ts"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "plugin-marketplace",
|
||||
"audiences": ["operator", "contributor"],
|
||||
"stability": "experimental",
|
||||
"docs": ["plugins-marketplace"],
|
||||
"sources": ["apps/backend/internal/plugins/marketplace/catalog.go", "apps/backend/internal/plugins/marketplace/sourcestore.go", "apps/web/lib/api/domains/marketplace-api.ts"],
|
||||
"tests": ["apps/backend/internal/plugins/marketplace/catalog_test.go", "apps/backend/internal/plugins/marketplace/sourcestore_test.go", "apps/web/hooks/domains/plugins/use-marketplace.test.ts"]
|
||||
"sources": [
|
||||
"apps/backend/internal/plugins/marketplace/catalog.go",
|
||||
"apps/backend/internal/plugins/marketplace/sourcestore.go",
|
||||
"apps/web/lib/api/domains/marketplace-api.ts"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/internal/plugins/marketplace/catalog_test.go",
|
||||
"apps/backend/internal/plugins/marketplace/sourcestore_test.go",
|
||||
"apps/web/hooks/domains/plugins/use-marketplace.test.ts"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "websocket-protocol",
|
||||
"audiences": ["contributor", "integrator"],
|
||||
"stability": "stable",
|
||||
"docs": ["websocket-api", "architecture", "extending-kandev"],
|
||||
"sources": ["apps/backend/pkg/websocket/actions.go", "apps/backend/pkg/websocket/handler.go"],
|
||||
"tests": ["apps/backend/pkg/websocket/handler_test.go", "apps/backend/pkg/websocket/handler_race_test.go"]
|
||||
"sources": [
|
||||
"apps/backend/pkg/websocket/actions.go",
|
||||
"apps/backend/pkg/websocket/handler.go"
|
||||
],
|
||||
"tests": [
|
||||
"apps/backend/pkg/websocket/handler_test.go",
|
||||
"apps/backend/pkg/websocket/handler_race_test.go"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "contributor-workflow",
|
||||
"audiences": ["contributor"],
|
||||
"stability": "stable",
|
||||
"docs": ["contributing", "architecture", "backend-development", "web-development", "testing", "remote-cloud-environment", "extending-kandev", "release-process"],
|
||||
"docs": [
|
||||
"contributing",
|
||||
"architecture",
|
||||
"backend-development",
|
||||
"web-development",
|
||||
"testing",
|
||||
"remote-cloud-environment",
|
||||
"extending-kandev",
|
||||
"release-process"
|
||||
],
|
||||
"sources": ["CONTRIBUTING.md", "Makefile"],
|
||||
"tests": ["scripts/lint-harness-files.test.py", ".github/scripts/lint-action-pinning_test.py"]
|
||||
"tests": [
|
||||
"scripts/lint-harness-files.test.py",
|
||||
".github/scripts/lint-action-pinning_test.py"
|
||||
]
|
||||
}
|
||||
],
|
||||
"exclusions": {
|
||||
"settingsRoutes": [
|
||||
{ "route": "/settings/changelog", "reason": "Redirect to System updates." },
|
||||
{ "route": "/settings/general/changes-panel", "reason": "Legacy redirect to Appearance." },
|
||||
{ "route": "/settings/general/chat-input", "reason": "Legacy redirect to Keyboard Shortcuts." },
|
||||
{ "route": "/settings/general/resource-metrics", "reason": "Legacy redirect to Appearance." },
|
||||
{ "route": "/settings/general/shell", "reason": "Legacy redirect to Terminal." },
|
||||
{ "route": "/settings/plugins", "reason": "Experimental feature intentionally omitted until its public contract stabilizes." },
|
||||
{
|
||||
"route": "/settings/changelog",
|
||||
"reason": "Redirect to System updates."
|
||||
},
|
||||
{
|
||||
"route": "/settings/general/changes-panel",
|
||||
"reason": "Legacy redirect to Appearance."
|
||||
},
|
||||
{
|
||||
"route": "/settings/general/chat-input",
|
||||
"reason": "Legacy redirect to Keyboard Shortcuts."
|
||||
},
|
||||
{
|
||||
"route": "/settings/general/resource-metrics",
|
||||
"reason": "Legacy redirect to Appearance."
|
||||
},
|
||||
{
|
||||
"route": "/settings/general/shell",
|
||||
"reason": "Legacy redirect to Terminal."
|
||||
},
|
||||
{
|
||||
"route": "/settings/plugins",
|
||||
"reason": "Experimental feature intentionally omitted until its public contract stabilizes."
|
||||
},
|
||||
{ "route": "/settings/system", "reason": "Redirect to System status." },
|
||||
{ "route": "/settings/system/message-queue", "reason": "Legacy redirect to General Message Queue." }
|
||||
{
|
||||
"route": "/settings/system/message-queue",
|
||||
"reason": "Legacy redirect to General Message Queue."
|
||||
}
|
||||
],
|
||||
"mcpTools": []
|
||||
}
|
||||
|
||||
@@ -390,6 +390,106 @@ A successful create returns the MR URL and asynchronously records it against the
|
||||
|
||||
</details>
|
||||
|
||||
## Bitbucket
|
||||
|
||||
> [!EXPERIMENTAL]
|
||||
> Bitbucket uses Kandev's experimental plugin platform. Package signatures are
|
||||
> not enforced yet, so the official plugin follows the same unsigned install
|
||||
> path as current plugins; signature enforcement is deferred.
|
||||
|
||||
Bitbucket support is provided by the separately installed **Bitbucket** plugin.
|
||||
Install a package built for the running Kandev host from **Settings > Plugins**,
|
||||
then open its **Bitbucket** entry in the Integrations section. The connection is
|
||||
workspace-specific: configure each Kandev workspace that should discover
|
||||
repositories, launch tasks, link pull requests, or use Bitbucket review and
|
||||
watch workflows.
|
||||
|
||||
### Connect Bitbucket Cloud
|
||||
|
||||
Choose **Bitbucket Cloud**, enter the Bitbucket workspace slug or ID, then pick
|
||||
one of these authentication methods:
|
||||
|
||||
| Method | Required values | Use when |
|
||||
|---|---|---|
|
||||
| API token | Atlassian account email and API token | A workspace-scoped, non-interactive connection is sufficient. |
|
||||
| OAuth 2.0 | OAuth client ID and secret, then complete the browser flow | Access should be granted interactively and refreshed by Bitbucket. |
|
||||
|
||||
For a [scoped Cloud API token](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/), grant `read:user:bitbucket`,
|
||||
`read:repository:bitbucket`, `write:repository:bitbucket`,
|
||||
`read:pullrequest:bitbucket`, and `write:pullrequest:bitbucket`. The write
|
||||
grants are needed for Git push, pull-request creation/review mutations, and
|
||||
other enabled write actions; omit them only if those operations should fail
|
||||
closed. For OAuth, enable Account read plus Repository and Pull request
|
||||
read/write permissions on the consumer; the plugin requests those scopes in
|
||||
the authorization flow.
|
||||
|
||||
For OAuth, copy the read-only callback URL that the plugin shows into the
|
||||
Bitbucket OAuth consumer. It is derived from the current Kandev origin; changing
|
||||
that origin requires updating the consumer redirect URI before reconnecting.
|
||||
Select **Check connection** and wait for the health card to report
|
||||
**Connected** before browsing repositories.
|
||||
|
||||
### Connect Bitbucket Data Center
|
||||
|
||||
Choose **Bitbucket Data Center**, enter the full HTTPS base URL (including any
|
||||
context path such as `/bitbucket`), and select the narrowest credential that
|
||||
matches your server:
|
||||
|
||||
| Method | Required values |
|
||||
|---|---|
|
||||
| Personal access token | Bitbucket username and PAT. |
|
||||
| Project access token | Project token. |
|
||||
| Repository access token | Repository token. |
|
||||
| OAuth 2.0 | Bitbucket username, OAuth client ID and secret, then browser authorization. |
|
||||
|
||||
The Data Center OAuth incoming application link must allow `REPO_READ` and
|
||||
`REPO_WRITE`. PATs and project/repository tokens likewise need read access for
|
||||
discovery/review and write access for push, pull-request, and review mutations.
|
||||
|
||||
Data Center deployments differ in their enabled REST and OAuth capabilities.
|
||||
The plugin reports unavailable operations from the connected server rather than
|
||||
assuming Cloud behavior. Use a trusted HTTPS URL; test-only insecure endpoints
|
||||
are not accepted by the normal connection flow.
|
||||
|
||||
### What the plugin adds
|
||||
|
||||
With a healthy connection, the plugin contributes Bitbucket repository discovery
|
||||
to **New Task**, credential-free remote inspection/branch lookup, task link and
|
||||
launch actions, a provider-neutral review panel, pull-request create/update and
|
||||
review actions where the server grants them, and workspace pull-request watches.
|
||||
Watches persist their cursor and reservations so a restart can reconcile a
|
||||
partially created task; they still depend on the configured provider identity
|
||||
and its current access.
|
||||
|
||||
Task Git credentials are brokered per verified Bitbucket provider/workspace/
|
||||
task/repository scope. The plugin returns credentials transiently; Kandev does
|
||||
not persist them in task metadata or remote URLs. Rotating credentials,
|
||||
disconnecting the workspace, disabling the plugin, or uninstalling it revokes
|
||||
the provider's leases so an already-issued helper fails closed. Configure
|
||||
executor SSH credentials separately for SSH remotes.
|
||||
|
||||
### Security and limitations
|
||||
|
||||
The plugin stores only credential-free connection settings in plugin state and
|
||||
keeps tokens, refresh tokens, and OAuth client secrets in Kandev's encrypted
|
||||
plugin secret vault. Existing secrets are never displayed; leave a secret empty
|
||||
only when the UI says it will retain the saved value. **Disconnect Bitbucket**
|
||||
removes that workspace's Bitbucket connection and stored plugin credentials.
|
||||
|
||||
Install plugins only from sources you trust. A plugin backend runs as a Kandev
|
||||
subprocess and its native UI runs in the Kandev origin, so capabilities are
|
||||
permission gates, not an operating-system or browser sandbox. Limit Bitbucket
|
||||
tokens to the repositories and write operations the workspace needs, and review
|
||||
the plugin's requested `api_read`, `api_write`, `state`, and `secrets`
|
||||
capabilities before installation.
|
||||
|
||||
The plugin does not turn a Bitbucket API credential into unrestricted executor
|
||||
access. A task can show a Bitbucket pull request while its selected executor
|
||||
cannot push; use the task's generated HTTPS credential path or separately
|
||||
configured SSH credentials. Dynamic `#` references and review actions are
|
||||
reauthorized against the active connection at use time, so a removed grant or
|
||||
disconnected connection is denied rather than using cached authority.
|
||||
|
||||
## Azure DevOps
|
||||
|
||||
<details>
|
||||
|
||||
@@ -47,12 +47,12 @@ min_kandev_version: "0.78.0" # optional
|
||||
capabilities:
|
||||
events: ["task.created", "task.state_changed", "agent.completed"]
|
||||
api_read: ["tasks", "agent_profiles"] # gates the Host data-reader RPCs
|
||||
api_write: ["tasks"] # gates Tasks().Create/Update
|
||||
api_write: ["tasks", "messages"] # gates Host task and message writes
|
||||
state: true
|
||||
secrets: true
|
||||
agent_invoke: true # gates Host.InvokeUtilityAgent
|
||||
auth: true # gates external (OIDC/SAML) login, see ADR 0050
|
||||
user_state: true # gates host.storage (per-user browser storage)
|
||||
agent_invoke: true # gates Host.InvokeUtilityAgent
|
||||
auth: true # gates external (OIDC/SAML) login; see ADR 0050
|
||||
user_state: true # gates host.storage (per-user browser storage)
|
||||
|
||||
webhooks:
|
||||
- key: "slack-events"
|
||||
@@ -61,6 +61,19 @@ webhooks:
|
||||
access: public # public (default) or authenticated
|
||||
max_body_bytes: 4194304 # public maximum 4 MiB; authenticated maximum 16 MiB
|
||||
|
||||
actions: # authenticated browser-to-plugin calls
|
||||
- key: "connection.save"
|
||||
scope: "workspace" # workspace | task | repository
|
||||
max_body_bytes: 65536 # 1 through 1048576
|
||||
|
||||
repository_providers: ["acme"] # optional provider ids owned while active
|
||||
reference_sources: # optional dynamic composer sources
|
||||
- source: "acme-pull-requests"
|
||||
provider: "acme"
|
||||
kind: "pull_request"
|
||||
display_name: "Acme pull requests"
|
||||
kind_label: "Pull request"
|
||||
|
||||
auth_providers: # login buttons (needs capabilities.auth)
|
||||
- id: "google"
|
||||
display_name: "Google"
|
||||
@@ -126,53 +139,59 @@ ui: # optional native frontend plugin
|
||||
<details>
|
||||
<summary>Complete field reference and validation rules</summary>
|
||||
|
||||
| Field | Required | Type | Notes |
|
||||
|---|---|---|---|
|
||||
| `id` | yes | string | Must match `^[a-z0-9][a-z0-9._-]*$` (lowercase alphanumeric, dots, underscores, hyphens; must start with a lowercase alphanumeric). Directory name under `~/.kandev/plugins/`. |
|
||||
| `api_version` | yes | int | Must be exactly `1`. Any other value is rejected. |
|
||||
| `version` | yes | string | Free-form; used as the version directory name (`~/.kandev/plugins/<id>/<version>/`). |
|
||||
| `display_name` | no | string | Shown in Settings > Plugins. |
|
||||
| `description` | no | string | Shown in Settings > Plugins. |
|
||||
| `author` | no | string | Free-form. |
|
||||
| `categories` | no | string[] | Each entry must be one of `connector`, `automation`, `tools`, `analytics`. Unknown values are rejected. |
|
||||
| `icon` | no | string | Package-relative path (e.g. `icon.svg`) to an image the package ships, rendered on the [marketplace](plugins-marketplace.md) card and in plugin lists. The registry index-build resolves it to an absolute `icon_url`; for an installed plugin it is served from the extracted package. Omit it and the card falls back to a letter tile. |
|
||||
| `repo_url` | no | string | Absolute `http(s)` URL to the plugin's source repository. Rendered as a "Repo" link in Settings > Plugins (both the installed list and the plugin detail). Any other scheme (e.g. `javascript:`) is rejected at registration. Distinct from the marketplace card's `repo_url`, which the registry derives from `plugins.yaml`; declare this in the manifest so sideloaded and directly-installed plugins also carry the link. |
|
||||
| `runtime.type` | conditionally | string | `"binary"` is the only supported value. Setting it (vs. leaving it empty) makes the manifest **runtime-managed**: see "Managed vs. legacy" below. |
|
||||
| `runtime.executables` | required when `runtime.type: binary` | map\<string,string\> | Key is `<goos>-<goarch>` (e.g. `linux-amd64`, `darwin-arm64`, `windows-amd64`); value is a clean, package-relative path under `server/` (no leading `/`, no `..` segments). At least one entry required; the running host's key must be present at install time. Windows values end in `.exe`. |
|
||||
| `min_kandev_version` | no | string | Lowest Kandev version this plugin supports. Enforced at **install time**: installing onto an older Kandev fails with `requires kandev >= <version>, running <version>` and nothing is registered. Already-installed plugins are never re-checked at load or start. A Kandev built from source reports the version `dev` and skips the check entirely, so local development is unaffected. Compare as dotted numeric segments (`0.78.0`); a `v` prefix does not parse as a number and falls back to a string comparison. |
|
||||
| `capabilities.events` | no | string[] | Bus subjects (or wildcard patterns) this plugin subscribes to. See "Event subscription vocabulary" below. |
|
||||
| `capabilities.api_read` | no | string[] | Gates the Host data API's read-only accessors. Each entry is a resource name: `tasks`, `sessions`, `messages`, `workspaces`, `workflows`, `agent_profiles`, `repositories`. Calling the matching `Host` accessor (e.g. `Tasks()`) without its resource declared returns gRPC `PermissionDenied`. See "Host data API resource vocabulary" below. |
|
||||
| `capabilities.api_write` | no | string[] | Gates Host data writes. Current resources are `tasks` (`Tasks().Create/Update`) and `messages` (`Messages().Send`); reads and writes are gated independently. |
|
||||
| `capabilities.state` | no | bool | Gates `Host.GetState`/`SetState`/`DeleteState`/`ListState`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
|
||||
| `capabilities.secrets` | no | bool | Gates `Host.RevealSecret`/`GetSecret`/`SetSecret`/`DeleteSecret`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
|
||||
| `capabilities.agent_invoke` | no | bool | Gates `Host.InvokeUtilityAgent`; a one-shot completion run by the utility agent selected for this plugin. Declare a `utility_agent` config property with `type: string` and `format: utility-agent`; Settings > Plugins renders the picker. The selected utility agent resolves its own enabled ACP profile. Calling without this capability returns gRPC `PermissionDenied`; calling without a valid profile-backed selection returns gRPC `FailedPrecondition`. See ADR 0048. |
|
||||
| `capabilities.auth` | no | bool | Lets the plugin log a visitor in against an external IdP (OIDC/SAML). Its webhook validates the token, then asserts the identity to Kandev via the `X-Kandev-Auth-Login` response header (`{provider, subject, email, display_name}`); Kandev mints the session and sets the cookie; the plugin never sees the token. Requires authentication enabled; new users are provisioned as members, and Kandev never creates an admin nor auto-links to an existing admin account. **You MUST only assert an email the IdP verified as owned by the subject; a spoofed email claim is account takeover.** Highest-privilege capability; grant only to trusted plugins. See ADR 0050. |
|
||||
| `capabilities.user_state` | no | bool | Gates `host.storage` (`get`/`set`/`delete`/`list`/`subscribe`), the authenticated per-user browser storage surface at `/api/plugins/{id}/user-state/...`. Unlike `capabilities.state` (the gRPC `Host.SetState` family, written by the plugin's own backend), this is reachable directly from the plugin's frontend bundle with no Go backend required; every read/write is scoped to the calling user. Calling the route without this capability returns `403`. See [Authoring a plugin](plugins-authoring.md) and the per-user-plugin-storage decision record. |
|
||||
| `webhooks[].key` | yes | string | Must be unique within the manifest. Used in the relay path `POST /api/plugins/{id}/webhooks/{key}`. |
|
||||
| `webhooks[].description` | no | string | Free-form. |
|
||||
| `webhooks[].method` | no | string | **Informational only**: kandev does not validate or enforce the inbound HTTP method against this value. |
|
||||
| `webhooks[].access` | no | string | `public` (default) allows anonymous callers; `authenticated` requires a Kandev identity. Cookie-authenticated browser calls remain subject to Kandev's same-origin policy. |
|
||||
| `webhooks[].max_body_bytes` | no | int | Request-body limit for this key. Defaults to 4 MiB. Public webhooks cannot exceed 4 MiB; authenticated webhooks can request up to 16 MiB. Plugins using this field should declare the first supporting `min_kandev_version`. |
|
||||
| `auth_providers[]` | no | object[] | Login buttons this plugin contributes to the pre-auth login screen (needs `capabilities.auth`). Each is `{ id, display_name, initiate }`, where `initiate` names one of the plugin's `webhooks[].key` values: the button navigates to that webhook, which 302-redirects to the IdP. Surfaced anonymously in the boot payload as `auth.ssoProviders`. |
|
||||
| `config_schema` | no | object | JSON-Schema-like object driving the settings form at **Settings > Plugins > `<plugin>`** (`GET /api/plugins/{id}/config` and `PATCH /api/plugins/{id}`). See "Config schema validation and secret fields" below. |
|
||||
| `agent_tools` | no | object[] | Task-aware MCP tools implemented by the managed plugin's optional `AgentToolPlugin` SDK interface. Each declaration has a local `name`, `description`, `surfaces`, required `input_schema`, optional `output_schema`, and optional MCP annotation hints. At most 16 tools are allowed. |
|
||||
| `agent_tools[].name` | yes* | string | Plugin-local name matching `^[a-z0-9][a-z0-9_]{0,31}$`. Kandev derives the global MCP name; authors cannot choose it. |
|
||||
| `agent_tools[].surfaces` | yes* | string[] | One or both of `kanban-task` and `office-task`. Plugin tools are not exposed to `configuration` or `external` MCP surfaces. |
|
||||
| `agent_tools[].input_schema` | yes* | object | Compiled object-root JSON Schema, at most 64 KiB serialized. Kandev rejects unknown top-level arguments before invoking the plugin. |
|
||||
| `agent_tools[].output_schema` | no | object | Optional compiled object-root JSON Schema applied to structured plugin results. |
|
||||
| `agent_tools[].annotations` | no | object | MCP hints: `read_only_hint`, `destructive_hint`, `idempotent_hint`, and `open_world_hint`. Omitted values use conservative host defaults. |
|
||||
| `ui.bundle` | no | string | Root-relative path (must start with `/`, e.g. `/ui/bundle.js`) to the plugin's native UI ES module, served at `GET /api/plugins/{id}/bundle`. |
|
||||
| `ui.styles` | no | string[] | Root-relative CSS paths (each must start with `/`), served at `GET /api/plugins/{id}/ui/*` and injected as `<link>` tags on load. |
|
||||
| `ui.pages` | no | object[] | Optional declarative metadata accepted by the manifest model. The current frontend does not render these entries; a native bundle registers its supported routes/nav/slots at runtime, so most plugins omit `ui.pages`. |
|
||||
| `ui.pages[].key` | yes* | string | Stable identifier for the page (*required when a page entry is present). |
|
||||
| `ui.pages[].title` | yes* | string | Display title. |
|
||||
| `ui.pages[].path` | yes* | string | Route path for the page. |
|
||||
| `ui.pages[].surface` | yes* | string | Metadata enum (`settings` · `task-panel` · `main-nav`) validated by the manifest parser. It is not a current frontend mount; use the registry hooks in the authoring guide. |
|
||||
| `ui.keybindings` | no | object[] | Declares plugin keybindings bound at runtime via `registerKeybinding`. Requires `ui.bundle`. |
|
||||
| `ui.keybindings[].id` | yes* | string | Stable, plugin-local slug (*required when a keybinding entry is present). Must match `^[a-z0-9][a-z0-9-]*$` and be unique within this plugin's own `ui.keybindings` list, not globally; the effective shortcut is namespaced `plugin:{pluginId}:{id}`. |
|
||||
| `ui.keybindings[].default` | yes* | string | Default combo string. `+`-separated tokens: zero or more modifiers from `mod`, `ctrl`, `cmd`, `meta`, `alt`, `option`, `shift` (`mod` = ⌘ on macOS, Ctrl elsewhere) plus exactly one non-modifier key. `shift` may not combine with a digit or symbol key; the browser reports the shifted glyph for those keys, so the combo could never match. |
|
||||
| `ui.keybindings[].description` | yes* | string | Non-empty, human-readable label shown in **Settings > Keyboard Shortcuts**. |
|
||||
| `ui.keybindings[].allow_in_editor` | no | boolean | Lets this binding fire while an `input`, `textarea` or contenteditable holds focus. Defaults to `false`, so a plugin cannot shadow ordinary typing. Only accepted on a combo carrying a `ctrl`/`cmd`/`mod`/`alt` modifier; `shift` alone does not count, since `shift+a` is just a capital A. Kandev re-applies that requirement to the *effective* combo, so a user override that drops the modifier reverts this binding to the default skip-while-typing behaviour rather than intercepting ordinary keystrokes. Declare it only when the binding exists to act on the focused field (dictation into the composer is the canonical case). |
|
||||
| Field | Required | Type | Notes |
|
||||
| ---------------------------------- | ------------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | yes | string | Must match `^[a-z0-9][a-z0-9._-]*$` (lowercase alphanumeric, dots, underscores, hyphens; must start with a lowercase alphanumeric). Directory name under `~/.kandev/plugins/`. |
|
||||
| `api_version` | yes | int | Must be exactly `1`. Any other value is rejected. |
|
||||
| `version` | yes | string | Free-form; used as the version directory name (`~/.kandev/plugins/<id>/<version>/`). |
|
||||
| `display_name` | no | string | Shown in Settings > Plugins. |
|
||||
| `description` | no | string | Shown in Settings > Plugins. |
|
||||
| `author` | no | string | Free-form. |
|
||||
| `categories` | no | string[] | Each entry must be one of `connector`, `automation`, `tools`, `analytics`. Unknown values are rejected. |
|
||||
| `icon` | no | string | Package-relative path (e.g. `icon.svg`) to an image the package ships, rendered on the [marketplace](plugins-marketplace.md) card and in plugin lists. The registry index-build resolves it to an absolute `icon_url`; for an installed plugin it is served from the extracted package. Omit it and the card falls back to a letter tile. |
|
||||
| `repo_url` | no | string | Absolute `http(s)` URL to the plugin's source repository. Rendered as a "Repo" link in Settings > Plugins (both the installed list and the plugin detail). Any other scheme (e.g. `javascript:`) is rejected at registration. Distinct from the marketplace card's `repo_url`, which the registry derives from `plugins.yaml`; declare this in the manifest so sideloaded and directly-installed plugins also carry the link. |
|
||||
| `runtime.type` | conditionally | string | `"binary"` is the only supported value. Setting it (vs. leaving it empty) makes the manifest **runtime-managed**; see "Managed vs. legacy" below. |
|
||||
| `runtime.executables` | required when `runtime.type: binary` | map\<string,string\> | Key is `<goos>-<goarch>` (e.g. `linux-amd64`, `darwin-arm64`, `windows-amd64`); value is a clean, package-relative path under `server/` (no leading `/`, no `..` segments). At least one entry required; the running host's key must be present at install time. Windows values end in `.exe`. |
|
||||
| `min_kandev_version` | no | string | Lowest released Kandev version this plugin supports. Enforced at **install time**: installing onto an older release fails with `requires kandev >= <version>, running <version>` and nothing is registered. Already-installed plugins are never re-checked at load or start. Release values use up to three dotted numeric segments (`0.78.0`) and may have a leading `v`; malformed minimums are rejected. Non-release development and git-describe builds skip the compatibility gate. |
|
||||
| `capabilities.events` | no | string[] | Bus subjects (or wildcard patterns) this plugin subscribes to. See "Event subscription vocabulary" below. |
|
||||
| `capabilities.api_read` | no | string[] | Gates the Host data API's read-only accessors. Each entry is a resource name: `tasks`, `sessions`, `messages`, `workspaces`, `workflows`, `agent_profiles`, `executor_profiles`, `repositories`. Calling the matching `Host` accessor (e.g. `Tasks()`) without its resource declared returns gRPC `PermissionDenied`. See "Host data API resource vocabulary" below. |
|
||||
| `capabilities.api_write` | no | string[] | Gates Host writes independently of `api_read`. `tasks` permits `Host.Tasks().Create` and `.Update`; `messages` permits `Host.Messages().Send`. Undeclared writes return gRPC `PermissionDenied`. |
|
||||
| `capabilities.state` | no | bool | Gates `Host.GetState`/`SetState`/`DeleteState`/`ListState`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
|
||||
| `capabilities.secrets` | no | bool | Gates `Host.RevealSecret`/`GetSecret`/`SetSecret`/`DeleteSecret`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
|
||||
| `capabilities.agent_invoke` | no | bool | Gates `Host.InvokeUtilityAgent`: a one-shot completion run by the utility agent selected for this plugin. Declare a `utility_agent` config property with `type: string` and `format: utility-agent`; Settings > Plugins renders the picker. The selected utility agent resolves its own enabled ACP profile. Calling without this capability returns gRPC `PermissionDenied`; calling without a valid profile-backed selection returns gRPC `FailedPrecondition`. See ADR 0048. |
|
||||
| `capabilities.auth` | no | bool | Lets the plugin log a visitor in against an external IdP (OIDC/SAML). Its webhook validates the token, then asserts the identity to Kandev via the `X-Kandev-Auth-Login` response header (`{provider, subject, email, display_name}`); Kandev mints the session and sets the cookie, so the plugin never sees the token. Requires authentication enabled; new users are provisioned as members, and Kandev never creates an admin nor auto-links to an existing admin account. **You MUST only assert an email the IdP verified as owned by the subject; a spoofed email claim is account takeover.** Highest-privilege capability; grant only to trusted plugins. See ADR 0050. |
|
||||
| `capabilities.user_state` | no | bool | Gates `host.storage` (`get`/`set`/`delete`/`list`/`subscribe`), the authenticated per-user browser storage surface at `/api/plugins/{id}/user-state/...`. Unlike `capabilities.state` (the gRPC `Host.SetState` family, written by the plugin's own backend), this is reachable directly from the plugin's frontend bundle with no Go backend required; every read/write is scoped to the calling user. Calling the route without this capability returns `403`. See [Authoring a plugin](plugins-authoring.md) and the per-user-plugin-storage decision record. |
|
||||
| `webhooks[].key` | yes | string | Must be unique within the manifest. Used in the relay path `POST /api/plugins/{id}/webhooks/{key}`. |
|
||||
| `webhooks[].description` | no | string | Free-form. |
|
||||
| `webhooks[].method` | no | string | **Informational only**: kandev does not validate or enforce the inbound HTTP method against this value. |
|
||||
| `webhooks[].access` | no | string | `public` (default) allows anonymous callers; `authenticated` requires a Kandev identity. Cookie-authenticated browser calls remain subject to Kandev's same-origin policy. |
|
||||
| `webhooks[].max_body_bytes` | no | int | Request-body limit for this key. Defaults to 4 MiB. Public webhooks cannot exceed 4 MiB; authenticated webhooks can request up to 16 MiB. Plugins using this field should declare the first supporting `min_kandev_version`. |
|
||||
| `actions[]` | no | object[] | Authenticated, manifest-declared browser actions. They are distinct from public webhooks: the host validates the action key, limits the JSON body, authorizes the declared resource, and passes only a verified context to the plugin. |
|
||||
| `actions[].key` | yes\* | string | Unique non-empty action key, used at `POST /api/plugins/{id}/actions/{key}`. |
|
||||
| `actions[].scope` | yes\* | `workspace` \| `task` \| `repository` | Resource selector the host authorizes. A task-scoped invocation may additionally name one repository attached to that verified task. Use the canonical field name `scope`; `resource_scope` is only a legacy read-compatibility spelling and must not be authored. |
|
||||
| `actions[].max_body_bytes` | yes\* | int | Maximum size of the decoded untrusted `body`, from 1 through 1,048,576 bytes. The whole HTTP envelope has a slightly larger hard cap. |
|
||||
| `repository_providers` | no | string[] | Provider IDs this plugin owns while active. An active provider can register native repository discovery/URL inspection and may supply transient Git credentials. Duplicate ownership is rejected. |
|
||||
| `reference_sources[]` | no | object[] | Dynamic composer-reference source. Each entry declares `source`, `provider`, `kind`, `display_name`, and `kind_label`; `order` is optional. Candidate identity is not trusted: Kandev reauthorizes the canonical reference when it is submitted. |
|
||||
| `auth_providers[]` | no | object[] | Login buttons this plugin contributes to the pre-auth login screen (needs `capabilities.auth`). Each is `{ id, display_name, initiate }`, where `initiate` names one of the plugin's `webhooks[].key` values; the button navigates to that webhook, which 302-redirects to the IdP. Surfaced anonymously in the boot payload as `auth.ssoProviders`. |
|
||||
| `config_schema` | no | object | JSON-Schema-like object driving the settings form at **Settings > Plugins > `<plugin>`** (`GET /api/plugins/{id}/config` and `PATCH /api/plugins/{id}`). See "Config schema validation and secret fields" below. |
|
||||
| `agent_tools` | no | object[] | Task-aware MCP tools implemented by the managed plugin's optional `AgentToolPlugin` SDK interface. Each declaration has a local `name`, `description`, `surfaces`, required `input_schema`, optional `output_schema`, and optional MCP annotation hints. At most 16 tools are allowed. |
|
||||
| `agent_tools[].name` | yes\* | string | Plugin-local name matching `^[a-z0-9][a-z0-9_]{0,31}$`. Kandev derives the global MCP name; authors cannot choose it. |
|
||||
| `agent_tools[].surfaces` | yes\* | string[] | One or both of `kanban-task` and `office-task`. Plugin tools are not exposed to `configuration` or `external` MCP surfaces. |
|
||||
| `agent_tools[].input_schema` | yes\* | object | Compiled object-root JSON Schema, at most 64 KiB serialized. Kandev rejects unknown top-level arguments before invoking the plugin. |
|
||||
| `agent_tools[].output_schema` | no | object | Optional compiled object-root JSON Schema applied to structured plugin results. |
|
||||
| `agent_tools[].annotations` | no | object | MCP hints: `read_only_hint`, `destructive_hint`, `idempotent_hint`, and `open_world_hint`. Omitted values use conservative host defaults. |
|
||||
| `ui.bundle` | no | string | Root-relative path (must start with `/`, e.g. `/ui/bundle.js`) to the plugin's native UI ES module, served at `GET /api/plugins/{id}/bundle`. |
|
||||
| `ui.styles` | no | string[] | Root-relative CSS paths (each must start with `/`), served at `GET /api/plugins/{id}/ui/*` and injected as `<link>` tags on load. |
|
||||
| `ui.pages` | no | object[] | Optional declarative metadata accepted by the manifest model. The current frontend does not render these entries; a native bundle registers its supported routes/nav/slots at runtime, so most plugins omit `ui.pages`. |
|
||||
| `ui.pages[].key` | yes\* | string | Stable identifier for the page (\*required when a page entry is present). |
|
||||
| `ui.pages[].title` | yes\* | string | Display title. |
|
||||
| `ui.pages[].path` | yes\* | string | Route path for the page. |
|
||||
| `ui.pages[].surface` | yes\* | string | Metadata enum (`settings` · `task-panel` · `main-nav`) validated by the manifest parser. It is not a current frontend mount; use the registry hooks in the authoring guide. |
|
||||
| `ui.keybindings` | no | object[] | Declares plugin keybindings bound at runtime via `registerKeybinding`. Requires `ui.bundle`. |
|
||||
| `ui.keybindings[].id` | yes\* | string | Stable, plugin-local slug (_required when a keybinding entry is present). Must match `^[a-z0-9][a-z0-9-]_$`and be unique within this plugin's own`ui.keybindings`list, not globally; the effective shortcut is namespaced`plugin:{pluginId}:{id}`. |
|
||||
| `ui.keybindings[].default` | yes\* | string | Default combo string. `+`-separated tokens: zero or more modifiers from `mod`, `ctrl`, `cmd`, `meta`, `alt`, `option`, `shift` (`mod` = ⌘ on macOS, Ctrl elsewhere) plus exactly one non-modifier key. `shift` may not combine with a digit or symbol key; the browser reports the shifted glyph for those keys, so the combo could never match. |
|
||||
| `ui.keybindings[].description` | yes\* | string | Non-empty, human-readable label shown in **Settings > Keyboard Shortcuts**. |
|
||||
| `ui.keybindings[].allow_in_editor` | no | boolean | Lets this binding fire while an `input`, `textarea` or contenteditable holds focus. Defaults to `false`, so a plugin cannot shadow ordinary typing. Only accepted on a combo carrying a `ctrl`/`cmd`/`mod`/`alt` modifier; `shift` alone does not count. Kandev re-applies that requirement to the effective combo, so a user override that drops the modifier reverts to skip-while-typing behavior. |
|
||||
|
||||
`ui.pages` is declarative manifest metadata only and is not currently rendered
|
||||
by the frontend. A native bundle's runtime nav items, icons, routes, named
|
||||
@@ -202,15 +221,20 @@ recognizes its shape.
|
||||
|
||||
`capabilities.api_read` gates the read-only Host data accessors (ADR 0043,
|
||||
ADR 0047): each entry must be one of `tasks`, `sessions`, `messages`,
|
||||
`workspaces`, `workflows`, `agent_profiles`, `repositories`. Declaring a
|
||||
`workspaces`, `workflows`, `agent_profiles`, `executor_profiles`, `repositories`. Declaring a
|
||||
resource grants the matching `Host` accessor (`Tasks()`, `Sessions()`,
|
||||
`Messages()`, `Workspaces()`, `Workflows()`, `AgentProfiles()`,
|
||||
`Repositories()`, see [Authoring a plugin](plugins-authoring.md)); calling an
|
||||
`Repositories()`), or the optional `pluginsdk.ExecutorProfiles(host)` extension;
|
||||
see [Authoring a plugin](plugins-authoring.md). Calling an
|
||||
accessor for an undeclared resource returns gRPC `PermissionDenied`.
|
||||
`capabilities.api_write` gates the current Host data writes: `tasks` gates
|
||||
`Tasks().Create`/`Update`, and `messages` gates `Messages().Send`. A plugin may
|
||||
declare a read resource without its write capability, or vice versa. Calling a
|
||||
write without the matching declaration returns gRPC `PermissionDenied`.
|
||||
`capabilities.api_write` currently accepts `tasks` and `messages`. `tasks`
|
||||
enables `Host.Tasks().Create` and `.Update`; `messages` enables
|
||||
`Host.Messages().Send`. The host applies the same first-party task service and
|
||||
message-delivery path as its own UI/API, emits the normal events, stamps created
|
||||
rows/messages as `plugin:<id>`, and does not let a plugin supply that provenance.
|
||||
A plugin may declare a read resource without its write capability, or vice
|
||||
versa. Calling a write without the matching declaration returns gRPC
|
||||
`PermissionDenied`.
|
||||
|
||||
`messages` reads historical **conversation content** (`Messages().List`):
|
||||
one user/agent message per row (`id`, `session_id`, `task_id`, `turn_id`,
|
||||
@@ -307,7 +331,7 @@ just the subject itself (`task.created`).
|
||||
| Linear | `linear.new_issue` |
|
||||
| Sentry | `sentry.new_issue` |
|
||||
| Office (autonomous agents) | `office.agent.created`, `office.agent.updated`, `office.agent.status_changed`, `office.skill.created`, `office.skill.updated`, `office.project.created`, `office.project.updated`, `office.approval.created`, `office.approval.resolved`, `office.comment.created`, `office.cost.recorded`, `office.run.queued`, `office.run.processed`, `office.run.event_appended` (per-run), `office.routine.triggered`, `office.inbox.item`, `office.task.status_changed`, `office.task.updated`, `office.task.decision_recorded`, `office.task.review_requested`, `office.provider.health_changed`, `office.route_attempt.appended`, `office.routing.settings_updated` |
|
||||
| Cross-plugin | `plugin.<plugin_id>.<name>`; published by `Host.EmitEvent`; subscribe with `plugin.<other-plugin-id>.*` to react to another plugin's events. |
|
||||
| Cross-plugin | `plugin.<plugin_id>.<name>`: published by `Host.EmitEvent`; subscribe with `plugin.<other-plugin-id>.*` to react to another plugin's events. |
|
||||
|
||||
> Event list current as of 2026-07-16; regenerate from
|
||||
> `apps/backend/internal/events/types.go` if this page drifts from the code.
|
||||
|
||||
@@ -16,8 +16,9 @@ For building a plugin, see [Authoring a plugin](plugins-authoring.md). For the
|
||||
manifest schema, see [Plugin manifest reference](plugins-manifest.md).
|
||||
|
||||
Plugins are an operator-level, instance-wide capability, there is no
|
||||
per-user plugin access. They ship in the base product with no feature flag to
|
||||
turn on: **Settings > Plugins** is always available in the sidebar. Because
|
||||
per-user plugin access. Installing a plugin requires an administrator when
|
||||
authentication is enabled. They ship in the base product with no feature flag
|
||||
to turn on: **Settings > Plugins** is always available in the sidebar. Because
|
||||
loaded plugin code runs with backend privileges, install only plugins you
|
||||
trust, see [Security posture](#security-posture).
|
||||
|
||||
@@ -255,12 +256,13 @@ recorded and are cleared after successful recovery.
|
||||
it declared in its manifest: `state` gates the state RPCs, `secrets` gates
|
||||
the plugin-owned secret RPCs, and each read-only data accessor (tasks,
|
||||
sessions, workspaces, workflows, agent profiles, repositories) is gated
|
||||
individually via `api_read:<resource>` and `api_write:<resource>` for the
|
||||
implemented task/message Host writes. An undeclared capability returns gRPC
|
||||
`PermissionDenied` with a message naming the missing capability, checked by
|
||||
a server interceptor before the handler runs. `GetConfig` and `EmitEvent`
|
||||
are the only ungated RPCs: a plugin can always read its own config
|
||||
(secrets included) and emit events.
|
||||
individually via `api_read:<resource>`. Task create/update and message send
|
||||
are independently gated by `api_write:tasks` and `api_write:messages` and
|
||||
use Kandev's first-party service paths. An undeclared capability returns
|
||||
gRPC `PermissionDenied` with a message naming the missing capability,
|
||||
checked before the handler runs. `GetConfig` and `EmitEvent` are the only
|
||||
ungated RPCs: a plugin can always read its own config (secrets included)
|
||||
and emit events.
|
||||
- **Native UI plugins run in-origin with full app-store access.** This is an
|
||||
accepted tradeoff, not an oversight: a plugin bundle shares the kandev
|
||||
React instance and Zustand store so it can build UI indistinguishable from
|
||||
|
||||
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 14 KiB |
|
After Width: | Height: | Size: 9.4 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 55 KiB |
|
After Width: | Height: | Size: 15 KiB |
@@ -127,6 +127,7 @@ Per-workspace credentials and triage triggers for external services.
|
||||
| Spec | Status |
|
||||
|---|---|
|
||||
| [azure-devops-integration](azure-devops-integration/spec.md) | shipped |
|
||||
| [bitbucket-plugin](bitbucket-plugin/spec.md) | approved |
|
||||
| [slack](integrations/slack.md) | archived — moved to `kandev-plugin-slack` |
|
||||
| [external-mcp](integrations/external-mcp.md) | draft |
|
||||
| [mcp-tool-argument-validation](integrations/mcp-tool-argument-validation.md) | shipped |
|
||||
|
||||
@@ -0,0 +1,370 @@
|
||||
---
|
||||
status: approved
|
||||
created: 2026-07-31
|
||||
owner: kandev
|
||||
---
|
||||
|
||||
# Bitbucket Connector Plugin
|
||||
|
||||
## Why
|
||||
|
||||
Teams using Bitbucket Cloud or Bitbucket Data Center need repository, pull-request,
|
||||
and task workflows without putting Bitbucket API knowledge or credentials into the
|
||||
Kandev host. The connector must feel native where users already create, link, review,
|
||||
and reference work, while remaining independently releasable as an official plugin.
|
||||
|
||||
## What
|
||||
|
||||
- Kandev ships the official `kandev-plugin-bitbucket` from its dedicated public
|
||||
repository. Its manifest pins `min_kandev_version` to the first released host
|
||||
version containing the required generic contracts; it never guesses an unreleased
|
||||
version.
|
||||
- The initial release follows Kandev's current unsigned marketplace trust contract:
|
||||
the generated internal `checksums.txt` is mandatory, the host reports the package
|
||||
as unsigned, and neither repository claims cryptographically verified publisher
|
||||
provenance. Signing is future host-wide work rather than a Bitbucket release gate,
|
||||
as recorded in
|
||||
[ADR-2026-08-01-bitbucket-initial-release-remains-unsigned](../../decisions/2026-08-01-bitbucket-initial-release-remains-unsigned.md).
|
||||
- The plugin supports Bitbucket Cloud and Bitbucket Data Center through separate
|
||||
adapters behind one Bitbucket domain. Cloud and Data Center have full capability
|
||||
parity wherever their APIs provide an equivalent operation. Capability flags hide
|
||||
unavailable controls or explain version-specific limits; the UI never presents a
|
||||
non-working equivalent.
|
||||
- A workspace connects with Cloud API token or OAuth 2.0, and with Data Center
|
||||
personal/HTTP access token or OAuth 2.0 when its administrator configured an
|
||||
incoming OAuth application link. Cloud app passwords are not accepted. OAuth client
|
||||
registrations are bring-your-own per workspace; no client secret ships in the public
|
||||
plugin.
|
||||
- The plugin owns Bitbucket REST payloads, OAuth and token rules, product/version
|
||||
probes, pagination, rate-limit handling, health polling, secret refresh, connector
|
||||
screens, watches, normalized review/status data, and provider actions. The host owns
|
||||
reusable authenticated action, repository-provider, task-action, review-provider,
|
||||
reference-source, task ownership, credential-broker, and code-host presentation
|
||||
contracts. GitHub, GitLab, and compatible plugins use the same host-rendered task
|
||||
status and review-detail anatomy rather than provider-owned approximations.
|
||||
- Users browse/search repositories, select branches, inspect pull-request URLs, launch
|
||||
tasks from pull requests, link/unlink existing tasks, and create pull requests from
|
||||
a task checkout branch. Remote descriptors preserve the exact credential-free clone
|
||||
URL, including Data Center context paths.
|
||||
- Native **Create PR** remains conditional on a task checkout containing commits and
|
||||
having no linked change request. For a registered provider, Kandev keeps the shared
|
||||
dialog, pushes the verified checkout branch through its normal Git path, and then
|
||||
invokes the provider's authenticated create callback. Unsupported provider options,
|
||||
such as draft creation, are hidden rather than silently ignored. This boundary is
|
||||
recorded in
|
||||
[ADR-2026-08-10-plugin-change-request-mutations](../../decisions/2026-08-10-plugin-change-request-mutations.md).
|
||||
- Plugin task actions appear in native task surfaces. Inside the existing **Link**
|
||||
submenu, the required entry is named **Bitbucket Pull Request**; it never repeats the
|
||||
parent verb as “Link Bitbucket Pull Request.” Selecting it opens the same host-owned
|
||||
task change-request dialog used by GitHub: title and explanatory description, one
|
||||
labeled input, inline validation, Cancel and Save footer actions, disabled/submitting
|
||||
state, success toast, and close-on-success. Provider code owns reference parsing and
|
||||
the authenticated link mutation, not modal anatomy. Desktop and mobile expose the same
|
||||
capability and host-native dialog behavior.
|
||||
- Bitbucket pull requests appear through the native review-provider registry in desktop
|
||||
selectors, dock/detail panels, task center, and mobile review navigation. The plugin
|
||||
maps Bitbucket detail, checks, reviews, comments, and capabilities into the host's
|
||||
provider-neutral change-request model and renders the same host-owned detail component
|
||||
as GitHub. The plugin supplies callbacks for supported mutations; the host owns header,
|
||||
sections, action placement, loading/error anatomy, scrolling, and responsive behavior.
|
||||
Unsupported Cloud/Data Center capabilities are omitted or explained without changing
|
||||
the shared layout.
|
||||
- Linked Bitbucket pull requests expose host-owned unlink controls in shared desktop
|
||||
popovers/review anatomy and touch-sized mobile surfaces. Unlink removes only the
|
||||
selected task association, refreshes review/status data, and immediately removes the
|
||||
corresponding task indicator without deleting the remote pull request. An explicit
|
||||
unlink suppresses source-branch auto-link for that task/pull-request pair until a
|
||||
manual relink and detaches watch ownership without deleting the task.
|
||||
- Composer `#` search consumes the plugin's dynamically registered
|
||||
`bitbucket`/`pull_request` reference source. Kandev constructs canonical reference
|
||||
identity, and every selected reference is reauthorized by the live plugin at message
|
||||
submission so stale, tampered, cross-workspace, or disabled-plugin selections fail
|
||||
closed.
|
||||
- **Settings > Integrations > Bitbucket** provides connection/authentication, health,
|
||||
and saved-watch management through the plugin's native integration-settings
|
||||
contribution. The `/bitbucket` page uses the same host-owned dashboard primitives
|
||||
as `/github` and `/gitlab`: compact scope controls, result title/count, repository
|
||||
and query filters, refresh, and one full-width bordered pull-request
|
||||
list. Rows use the same inert-container, external-title, metadata, linked-task, and
|
||||
sole **Task** preset-menu anatomy. Preset selection opens the native
|
||||
`TaskCreateDialog` directly; no Bitbucket launch intermediary or row-level Review
|
||||
action exists. Dashboard scope selection commits its normalized filter into the
|
||||
visible query field, matching GitHub/GitLab; manually committed query changes and
|
||||
the active scope always drive the same provider request. Scope and pull-request
|
||||
state glyphs use host-owned semantic integration icons rather than plugin-drawn
|
||||
copies. Review remains in normal linked-task desktop/mobile review surfaces.
|
||||
The preset menu uses the exact first-party glyphs: eye for **Review**, message for
|
||||
**Address feedback**, and tool for **Fix CI**.
|
||||
Committed custom queries and repository filters can be named, saved, selected, and
|
||||
deleted with the same scope-bar workflow as GitHub/GitLab. Saved queries are
|
||||
per-user, per-workspace plugin state through `host.storage`; saving commits and stores
|
||||
the visible query draft even when the user has not pressed Enter first.
|
||||
Existing workspace repositories use the dialog's normal REST create path. First-use
|
||||
Bitbucket repositories use the dialog's optional create transport through the
|
||||
authenticated `tasks.launch` action; the server resolves the repository descriptor
|
||||
from the connected pull request and uses a per-dialog launch ID for retry-only
|
||||
deduplication. Browser payloads cannot nominate a trusted repository descriptor, and
|
||||
separate Task-menu launches may create separate tasks for the same pull request.
|
||||
After a Bitbucket repository is persisted, the dialog's native branch picker routes
|
||||
through the plugin's workspace-scoped `repositories.branches` action. The host derives
|
||||
its descriptor from that repository row, so the picker has Cloud/Data Center branches
|
||||
without a GitHub fallback, local-clone dependency, or browser-selected authority.
|
||||
This boundary is recorded in
|
||||
[ADR-2026-08-06-plugin-code-host-dashboard-parity](../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md).
|
||||
Watch creation and management remain in **Settings > Integrations > Bitbucket**;
|
||||
the dashboard does not add a provider-specific Watch button absent from GitHub/GitLab.
|
||||
- Watches use authenticated polling, not Bitbucket event webhooks. OAuth callback is
|
||||
the only required public webhook in v1. A watch writes a durable `creating`
|
||||
reservation before task creation, stamps plugin/watch/external-PR ownership, and
|
||||
reconciles unfinished reservations after restart. Reset/delete previews its cascade
|
||||
and deletes only tasks owned by this plugin/watch; manually linked or adopted tasks
|
||||
remain.
|
||||
- Manual links, pull requests created from a task, and watch-created tasks all expose
|
||||
one durable task-to-pull-request association to the dashboard, native Review
|
||||
provider, and task-topbar status control. Restart recovery preserves watch-owned
|
||||
associations without duplicating them into manual-link state.
|
||||
- Task refresh detects an externally created open pull request by exact source-branch
|
||||
match against each host-verified Bitbucket checkout and persists that association
|
||||
idempotently. The browser cannot nominate the repository or branch, and a transient
|
||||
discovery failure never removes or hides existing links.
|
||||
- A linked Bitbucket pull request contributes normalized status through its registered
|
||||
review-provider snapshot. Kandev automatically renders that status in both places used
|
||||
by GitHub: the compact task-topbar pull-request control and the CI chip above the chat
|
||||
composer (including passthrough sessions). Both use the exact shared trigger and
|
||||
popover/drawer body, not a plugin slot or provider-owned lookalike. Desktop hover uses
|
||||
the same delay; touch/mobile uses the same bounded, internally scrollable drawer.
|
||||
Opening either surface refreshes immediately, the provider polls in the background
|
||||
around every 90 seconds, and clicking through opens the registered Bitbucket Review
|
||||
surface. Cloud Pipelines and Data Center build statuses are normalized from the pull
|
||||
request's source/head commit, never its destination commit.
|
||||
- The review provider exposes one bounded workspace association snapshot. Kandev uses
|
||||
it to render its semantic pull-request glyph beside linked tasks in task switcher,
|
||||
Kanban, and rich task-list rows, without issuing one provider request per task. On
|
||||
mouse hover or keyboard focus, that glyph opens the same host-owned structured
|
||||
pull-request summary used by GitHub (number, title, review, CI, and available state),
|
||||
resolving detail lazily through the registered review-provider snapshot. A plain
|
||||
count-only tooltip is not parity. Touch/mobile continues through the native task
|
||||
status and Review surfaces; no required information or action is hover-only.
|
||||
- Clone, fetch, and push resolve through the provider-neutral short-lived credential
|
||||
broker. Secrets never appear in clone URLs, task metadata/state, environment
|
||||
variables, command arguments, logs, or executor payloads.
|
||||
Initial host-side materialization carries the same host-derived workspace, task,
|
||||
active-session, repository, exact-host, and exact-path scope to the plugin; an
|
||||
incomplete scope is rejected instead of falling back to a workspace-only secret.
|
||||
Existing managed checkouts are refreshed through that exact scope before worktree
|
||||
creation; local and worktree execution then use refreshed refs without a second
|
||||
network operation.
|
||||
|
||||
## Capability matrix
|
||||
|
||||
| Capability | Cloud | Data Center |
|
||||
| --------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------- |
|
||||
| API token/PAT connection and health | Required | Required |
|
||||
| OAuth 2.0 connect and refresh | Required | Required when an incoming OAuth application link exists |
|
||||
| Repository/project browse and search | Required | Required |
|
||||
| Native repository picker, branch selection, and PR URL inspection | Required | Required |
|
||||
| Scoped clone/fetch/push credential broker | Required | Required |
|
||||
| Launch task, link/unlink, and create PR from task | Required | Required |
|
||||
| Native desktop/mobile review panel | Required | Required |
|
||||
| Composer `#` pull-request search and submitted context | Required | Required |
|
||||
| Queue, files/diff, commits, comments/threads, reviewers, approvals, merge/decline | Required | Required where server API supports thread semantics |
|
||||
| Status presentation | Pipelines | Commit/build status |
|
||||
| Watches with deduplicated task creation | Required | Required |
|
||||
| Bitbucket Issues | Not supported; use Jira | Not supported; use Jira |
|
||||
|
||||
## Connection, permissions, and secrets
|
||||
|
||||
Connection state is `unconfigured`, `checking`, `connected`, `auth_required`, or
|
||||
`unavailable`. Workspace-scoped encrypted plugin secrets hold token/PAT credentials,
|
||||
OAuth registrations, grants, and rotating refresh tokens. State stores only non-secret
|
||||
connection metadata and an atomically rotated credential generation. Refresh is
|
||||
singleflight per workspace/generation/connection epoch. Disconnect or connection
|
||||
replacement removes completed refresh data and fences an exchange already in flight;
|
||||
that stale result cannot be returned, cached, or persisted. Logs and returned errors
|
||||
redact headers, query parameters, and secret values.
|
||||
|
||||
The host authenticates browser actions through normal Kandev session middleware and
|
||||
authorizes every claimed workspace, task, and repository before dispatch. It derives
|
||||
task-to-workspace relationships server-side. Plugins receive verified actor/resource
|
||||
context separately from bounded untrusted JSON. The connector can create or cascade-
|
||||
delete only task trees stamped `metadata.source = "plugin:kandev-plugin-bitbucket"`;
|
||||
pre-existing task links remain plugin state rather than host-owned task provenance.
|
||||
|
||||
Data Center accepts private-network installations intentionally. Production connections
|
||||
require HTTPS, reject URL credentials, retain redirect origin, and enforce connect/read
|
||||
timeouts and response-size limits. HTTP is development-only behind an explicit setting.
|
||||
|
||||
## API and host contracts
|
||||
|
||||
The required generic seams are defined by
|
||||
[authenticated plugin actions](../../decisions/2026-07-31-authenticated-plugin-actions.md),
|
||||
[repository-provider extensions](../../decisions/2026-07-31-plugin-repository-provider-extensions.md),
|
||||
and [provider-neutral git credential brokerage](../../decisions/2026-07-31-provider-neutral-git-credential-broker.md).
|
||||
Their frozen protocol/UI references are
|
||||
[`GRPC-CONTRACT.md`](../../plans/plugins/GRPC-CONTRACT.md),
|
||||
[`HOST-DATA-API.proto`](../../plans/plugins/HOST-DATA-API.proto), and
|
||||
[`PLUGIN-API.md`](../../plans/plugins/PLUGIN-API.md).
|
||||
|
||||
The plugin declares actions including `connection.get`, `connection.save`,
|
||||
`oauth.start`, `repositories.list`, `pullrequests.get`, and `watches.update`; each
|
||||
has a resource scope and bounded body. It declares ownership of provider ID
|
||||
`bitbucket` and the `bitbucket`/`pull_request` reference source. The browser calls
|
||||
declared actions only through the authenticated host action route; public plugin
|
||||
webhooks remain reserved for provider callbacks.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- A disabled, unavailable, or timed-out action plugin returns a bounded actionable
|
||||
error; it does not expose the public webhook route as a browser fallback.
|
||||
- A failed connection, expired credential, or refresh denial transitions visibly to
|
||||
`auth_required` or `unavailable`; existing non-secret connection metadata stays
|
||||
intact. Health probes run around every 90 seconds with jitter/backoff.
|
||||
- Cloud rate limits and Data Center transient failures use adapter-owned bounded retry/
|
||||
backoff. Unsupported product/version capabilities show an unsupported explanation.
|
||||
- An invalid or incomplete provider descriptor, host/path mismatch, stale broker
|
||||
lease, disabled provider, or submission reauthorization denial fails closed.
|
||||
- Watch create/recovery failures preserve durable reservations and surface the last
|
||||
error. A reset/delete never removes a task whose plugin provenance does not match.
|
||||
|
||||
## Persistence guarantees
|
||||
|
||||
Plugin state persists connection metadata, capability probe result, watches, cursors,
|
||||
dedupe keys, reservations, links, and recovery/error state through the Host state API.
|
||||
Durable pull-request identity is provider ID plus provider connection scope plus
|
||||
immutable repository ID plus pull-request number; repository namespace/path and display
|
||||
keys are never dedupe authority. Provider cursors are bound to that immutable identity
|
||||
and their normalized query. Connection replacement pauses a bound watch before any
|
||||
provider request; explicit resume rebinds it and clears stale pagination state.
|
||||
Encrypted secrets persist separately. Credential broker leases are short-lived and
|
||||
non-durable; they are re-resolved from the live plugin and revoked on task/session/
|
||||
workspace teardown, plugin disable, connection reset, or credential-generation change.
|
||||
The plugin exposes that generation only as an opaque, non-secret credential binding;
|
||||
the host checks it before and after each lease redemption and fails closed when absent
|
||||
or changed. Plugin disable, error, or uninstall also immediately revokes every lease
|
||||
for its declared provider; exact repository path matching remains case-sensitive.
|
||||
|
||||
## Scenarios
|
||||
|
||||
- **GIVEN** the independently released Bitbucket UI bundle, **WHEN** it compiles or
|
||||
launches native task creation, **THEN** it consumes `@kandev/plugin-sdk` and typed
|
||||
`host.context` reads without copied host interfaces or private Zustand slice parsing.
|
||||
- **GIVEN** Bitbucket is active and a user pastes a URL owned by GitHub, GitLab, or
|
||||
another self-hosted provider, **WHEN** Kandev probes registered repository providers,
|
||||
**THEN** Bitbucket's workspace-scoped structured inspector returns no match and does
|
||||
not steal the URL by hostname/path heuristics or registration order.
|
||||
|
||||
- **GIVEN** a connected Cloud or Data Center workspace, **WHEN** a user selects a
|
||||
Bitbucket repository in native task creation, **THEN** Kandev persists the complete
|
||||
plugin-inspected descriptor and exact credential-free clone URL without host-side
|
||||
Bitbucket URL parsing.
|
||||
- **GIVEN** two Data Center connections share one authority but use different context
|
||||
roots, **WHEN** either imports the same project/repository slug, **THEN** Kandev keeps
|
||||
distinct rows and managed clones using the plugin's connection scope and immutable
|
||||
repository ID; it never adopts the other root or a legacy unscoped row.
|
||||
- **GIVEN** a persisted Bitbucket repository is materialized for a task session,
|
||||
**WHEN** Kandev requests the initial HTTPS clone credential, **THEN** the plugin
|
||||
receives the host-derived workspace, task, session, repository, exact-host, and
|
||||
exact-path scope, and missing or mismatched scope fails before Git runs.
|
||||
- **GIVEN** that managed checkout already exists and pull-before-worktree is enabled,
|
||||
**WHEN** a task session launches, **THEN** Kandev refreshes origin through the same
|
||||
exact plugin credential scope and performs no unauthenticated follow-up fetch or pull.
|
||||
- **GIVEN** an eligible task, **WHEN** a user opens a desktop task context/dropdown or
|
||||
visible mobile task action menu, **THEN** **Link → Bitbucket Pull Request** is
|
||||
represented by a **Bitbucket Pull Request** child item and invokes the plugin with
|
||||
verified current context.
|
||||
- **GIVEN** that item is selected, **WHEN** the user enters an invalid or valid Bitbucket
|
||||
pull-request reference, **THEN** the host renders GitHub-parity dialog geometry and
|
||||
footer behavior, keeps validation errors inline, and on success closes the dialog and
|
||||
shows a success toast after the authenticated task-scoped link completes.
|
||||
- **GIVEN** a Bitbucket pull request linked to a task, **WHEN** the user opens review
|
||||
on desktop or mobile, **THEN** the native review surface selects a normalized
|
||||
Bitbucket item and mounts the host-owned change-request detail anatomy used by GitHub,
|
||||
with Bitbucket data and only the actions its adapter declares.
|
||||
- **GIVEN** the plugin is disabled after a review panel, task action, or repository
|
||||
provider was registered, **WHEN** Kandev refreshes the plugin registry, **THEN**
|
||||
those registrations disappear, in-flight work is aborted, review selections close
|
||||
safely, and no host Bitbucket fallback remains.
|
||||
- **GIVEN** the plugin is active, **WHEN** a user opens the native integrations index
|
||||
or a workspace settings tree, **THEN** Bitbucket appears with its plugin-owned brand icon and
|
||||
native settings page, receives the selected workspace ID, and disappears from both
|
||||
surfaces when the plugin unloads.
|
||||
- **GIVEN** a connected Bitbucket workspace, **WHEN** the user opens `/bitbucket`,
|
||||
**THEN** the page uses the same list-first hierarchy, density, toolbar geometry,
|
||||
row anatomy, and restrained loading/error/empty treatment as `/github` and
|
||||
`/gitlab`; the host renders shared primitives rather than plugin-cloned markup.
|
||||
- **GIVEN** more than one provider page of repositories or pull requests, **WHEN** the
|
||||
user searches the repository filter or changes result pages, **THEN** the dashboard
|
||||
consumes opaque cursors, exposes every repository, and keeps a deterministic
|
||||
provider-neutral queue order without truncating before pagination.
|
||||
- **GIVEN** a pull request in that list, **WHEN** the user opens its **Task** menu,
|
||||
**THEN** the same compact preset menu as GitHub/GitLab appears and the chosen preset
|
||||
opens Kandev's native task dialog directly with repository, source branch, title,
|
||||
and prompt prefilled; the three preset rows use the exact native eye, message, and
|
||||
tool glyphs.
|
||||
- **GIVEN** a Bitbucket task is created or already linked, **WHEN** the user returns to
|
||||
the dashboard or opens task Review, **THEN** the row exposes the native linked-task
|
||||
indicator and review opens through the registered task review provider; there is no
|
||||
dashboard Review button or intermediate launch dialog on desktop or mobile.
|
||||
- **GIVEN** a linked Bitbucket pull request has normalized task status, **WHEN** its
|
||||
task-list indicator renders or its lazy desktop refresh completes, **THEN** the glyph
|
||||
uses the same failure, pending, review-wait, passing, merged, and muted color hierarchy
|
||||
as first-party code hosts without accepting provider CSS or Bitbucket-specific tones.
|
||||
- **GIVEN** a committed custom query or repository filter differs from a built-in
|
||||
preset, **WHEN** the user saves and names it, **THEN** it appears in the shared saved
|
||||
menu, survives reload for that user/workspace, restores the displayed query and
|
||||
repository filter when selected, and can be deleted.
|
||||
- **GIVEN** a pull request repository is not yet persisted in the workspace, **WHEN**
|
||||
the native task dialog submits or retries, **THEN** the authenticated plugin action
|
||||
creates from the server-resolved source repository exactly once for that dialog
|
||||
launch; opening the Task menu again may create another linked task.
|
||||
- **GIVEN** that Bitbucket repository is persisted, **WHEN** the native task dialog
|
||||
loads its branch picker, **THEN** Kandev invokes the active Bitbucket plugin with the
|
||||
stored provider descriptor and renders its branches without a GitHub request, a 500,
|
||||
or a local-clone fallback.
|
||||
- **GIVEN** a `#` Bitbucket pull-request result was selected, **WHEN** the message is
|
||||
submitted after the plugin was disabled, moved workspaces, or access changed,
|
||||
**THEN** submission reauthorization rejects it and no unapproved reference metadata
|
||||
reaches the queued message.
|
||||
- **GIVEN** a watch finds the same pull request concurrently or restarts during task
|
||||
creation, **WHEN** recovery runs, **THEN** the durable reservation and plugin-owned
|
||||
task metadata result in at most one created task; reset/delete previews and removes
|
||||
only that owned tree, and the recovered task remains associated with the pull request
|
||||
in dashboard, Review, and status queries.
|
||||
- **GIVEN** a task creates a Bitbucket pull request successfully, **WHEN** the result is
|
||||
returned or the task is reopened, **THEN** the new pull request is already associated
|
||||
with that task; a later association-state failure is reported without inviting a
|
||||
retry that could create a duplicate remote pull request.
|
||||
- **GIVEN** an eligible Bitbucket task has commits and no linked pull request, **WHEN**
|
||||
the user submits native **Create PR**, **THEN** Kandev pushes the selected checkout
|
||||
branch, verifies the selected session/repository worktree and passes its server-derived
|
||||
head branch to the active provider, associates the created pull request, and reports a
|
||||
post-push create failure as retryable without trusting a browser source branch or
|
||||
adding Bitbucket logic to `agentctl`.
|
||||
- **GIVEN** one or more Bitbucket pull requests are linked to a task, **WHEN** association
|
||||
data loads or one link is removed, **THEN** the native task-row/card glyph count and
|
||||
shared unlink controls update reactively on desktop and mobile while other links
|
||||
remain intact.
|
||||
- **GIVEN** an agent or user creates an open Bitbucket pull request externally from a
|
||||
task's checkout branch, **WHEN** that task refreshes, **THEN** the plugin discovers
|
||||
the exact source-branch match from host-verified repository data and links it without
|
||||
a manual URL paste.
|
||||
- **GIVEN** a linked pull request has source-commit pipeline/build statuses, **WHEN**
|
||||
the task topbar control or composer CI chip is opened on desktop or mobile, **THEN**
|
||||
the exact shared GitHub-grade status surface shows those checks, refreshes on open,
|
||||
and can open the registered Bitbucket Review panel without a provider-specific route.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Bitbucket Issues, Cloud app passwords, and a generic host Bitbucket API client.
|
||||
- Bitbucket-specific changes in `agentctl` pull-request automation or a new
|
||||
provider-specific WebSocket contract.
|
||||
- External Bitbucket webhooks for watches; authenticated polling is v1 behavior.
|
||||
- Pretending Cloud Pipelines and Data Center build statuses have identical APIs.
|
||||
- A Bitbucket-specific signing verifier or trust-root policy. The initial release uses
|
||||
the current checksum-verified, explicitly unsigned plugin contract.
|
||||
- Marketplace publication before required host contracts are released, package,
|
||||
desktop/mobile, and container credential-flow acceptance passes.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
[Bitbucket plugin implementation plan](../../plans/bitbucket-plugin/plan.md)
|
||||
@@ -1,13 +1,14 @@
|
||||
---
|
||||
status: building
|
||||
created: 2026-07-27
|
||||
updated: 2026-08-02
|
||||
updated: 2026-08-12
|
||||
owner: jcfs
|
||||
---
|
||||
|
||||
# Internationalization (i18n)
|
||||
|
||||
## Why
|
||||
|
||||
Kandev's i18n foundation lets migrated web surfaces externalize copy, switch
|
||||
locale, and format dates and numbers per language, but English is still the only
|
||||
human language shipped. Adding Simplified Chinese makes the existing localized
|
||||
@@ -15,11 +16,16 @@ surface usable by Chinese-speaking users while preserving English as the source
|
||||
language and the pseudo-locale as the migration QA oracle.
|
||||
|
||||
## What
|
||||
|
||||
- The web UI SHALL render all user-facing text through a translation layer
|
||||
(i18next `t("ns:key")` / react-i18next `<Trans>`), not from inline literals. "User-facing text"
|
||||
covers visible copy, `placeholder`, `aria-label`/`aria-description`, `title`,
|
||||
`alt`, toast/`sonner` messages, form-validation messages, empty-state and
|
||||
error copy, and confirm/dialog text.
|
||||
- Native UI plugins SHALL register plugin-owned catalogs through the public plugin SDK. Kandev
|
||||
SHALL isolate them by verified plugin identity, require English fallback copy, expose the active
|
||||
locale through imperative and reactive scoped translation APIs, and remove their resources with
|
||||
the plugin lifecycle. Plugin catalogs SHALL NOT mutate built-in or sibling-plugin namespaces.
|
||||
- English SHALL remain the source locale. The shipped human locales SHALL be
|
||||
`en`, `pt-pt`, and `zh-cn`; copy lives in per-namespace JSON catalogs keyed by
|
||||
stable ids. The `pseudo` catalog is generated from `en`, never hand-edited.
|
||||
@@ -92,6 +98,7 @@ merge. Sequence:
|
||||
currently in `SCREENS`) and the shared-task artifacts.
|
||||
|
||||
## Data model
|
||||
|
||||
i18n adds no server-side persistent entities. It introduces:
|
||||
|
||||
- **Message catalogs** — checked-in JSON under
|
||||
@@ -117,6 +124,7 @@ There is no SQLite or user-settings persistence for locale. The cookie is the
|
||||
single persisted source of truth and is hydrated into the store at boot.
|
||||
|
||||
## API surface
|
||||
|
||||
No new HTTP/WS contract is required to add a locale. Two integration points:
|
||||
|
||||
- **Go shell** (`apps/backend/internal/webapp/shell.go`): reads the
|
||||
@@ -134,8 +142,12 @@ Frontend module contract (new):
|
||||
- `apps/web/lib/i18n/formats.ts` — locale-aware `formatDate`, `formatRelative`
|
||||
(replacing `timeAgo`), `formatNumber`, `formatBytes` wrappers over `Intl` /
|
||||
`date-fns` with the active locale.
|
||||
- `@kandev/plugin-sdk` — `PluginRegistry.registerTranslations()` plus scoped
|
||||
`PluginHostApi.i18n.t()` and `useTranslation()` access. See
|
||||
[ADR-2026-08-12-plugin-localization-contract](../../decisions/2026-08-12-plugin-localization-contract.md).
|
||||
|
||||
## Scenarios
|
||||
|
||||
- **GIVEN** a fresh install with no locale cookie, **WHEN** the UI loads,
|
||||
**THEN** `<html lang>` is `en`, all text renders from the `en` catalog, and the
|
||||
language switcher shows English selected.
|
||||
@@ -176,6 +188,9 @@ Frontend module contract (new):
|
||||
falls back to its English default without throwing.
|
||||
- **GIVEN** a plural key (`x_one` / `x_other`) rendered with a `count`, **WHEN**
|
||||
count is 1 vs many, **THEN** i18next selects the matching form.
|
||||
- **GIVEN** two active plugins with the same message key, **WHEN** either translates that key and
|
||||
the locale changes, **THEN** each receives only its own message and reactive plugin surfaces
|
||||
rerender. **WHEN** one plugin is disabled, **THEN** only its catalog is removed.
|
||||
- **GIVEN** a production build, **WHEN** the language switcher renders, **THEN**
|
||||
English, Português (Portugal), and 简体中文 are offered and the pseudo-locale
|
||||
is not.
|
||||
@@ -188,6 +203,7 @@ Frontend module contract (new):
|
||||
the advisory path must not mask the gating one.
|
||||
|
||||
## Failure modes
|
||||
|
||||
- **Missing translation for the active locale** → i18next falls back to `en`,
|
||||
and an entirely unknown key renders as the key itself; the UI never blanks or
|
||||
throws. The `i18n:check` CI gate is what keeps unknown keys out.
|
||||
@@ -203,6 +219,7 @@ Frontend module contract (new):
|
||||
English `defaultProps`; no runtime dependency on the app i18n instance.
|
||||
|
||||
## Persistence guarantees
|
||||
|
||||
- The locale preference survives a kandev restart through the
|
||||
`kandev_locale` cookie.
|
||||
- Message catalogs are source-controlled build inputs; nothing i18n-related is
|
||||
@@ -211,6 +228,7 @@ Frontend module contract (new):
|
||||
switching locale is a pure client re-render.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Shipping human languages other than English, European Portuguese, and
|
||||
Simplified Chinese.
|
||||
- Translating the CLI launcher, logs, or ACP/agent output, and the ~1,100
|
||||
@@ -229,6 +247,7 @@ Frontend module contract (new):
|
||||
- A translation-management platform / vendor sync (Crowdin, Lokalise, etc.).
|
||||
|
||||
## Resolved decisions
|
||||
|
||||
- **Locale storage**: a dedicated `kandev_locale` cookie is the source of truth
|
||||
(so the Go shell sets `<html lang>` on first paint with no flash); it is
|
||||
hydrated into user-settings/store for the switcher UI. With no cookie set the
|
||||
|
||||
@@ -53,7 +53,8 @@ surfaces. The core stays small; the ecosystem grows independently.
|
||||
runtime"). This is the one in-process surface; the backend stays out-of-process
|
||||
(but is now kandev-managed, not operator-managed).
|
||||
- A plugin manifest declares identity, runtime executables (per OS/arch), capabilities,
|
||||
declared webhooks, config schema, and optional UI bundle.
|
||||
declared webhooks and authenticated actions, repository-provider and reference-source
|
||||
ownership, config schema, and optional UI bundle.
|
||||
- Plugins SHALL receive events, expose proxied external webhook
|
||||
endpoints, and read/write a plugin-scoped KV state — all over gRPC.
|
||||
- Plugins are distributed as a signed-or-unsigned release **tarball** and installed
|
||||
@@ -69,6 +70,21 @@ surfaces. The core stays small; the ecosystem grows independently.
|
||||
on crash or health-check failure. Operators no longer run or manage plugin processes
|
||||
themselves. The remote/self-hosted tier (`base_url` registration of an
|
||||
operator-run process kandev never spawns) is removed; see "Out of scope".
|
||||
- Plugin repository providers, task actions, and review panels register through
|
||||
revocable generic frontend contracts. A provider plugin can participate in native
|
||||
task creation, Link menus, desktop/mobile review surfaces, and composer `#` search
|
||||
without a host-specific provider branch.
|
||||
- The independently consumable, runtime-free `@kandev/plugin-sdk` package is the
|
||||
frontend author contract. Official plugins use its typed `host.context` reads and
|
||||
named UI/provider contracts instead of importing or copying private Kandev store,
|
||||
React, Zustand, or `@/` application types.
|
||||
- First-party-parity code-host dashboards use host-owned provider-neutral list,
|
||||
toolbar, scope, task-menu, and linked-task primitives exposed through `host.ui`.
|
||||
Plugins provide normalized data and callbacks; task presets open the native
|
||||
`TaskCreateDialog`, while review remains owned by the task review-provider surface.
|
||||
- Native UI plugins register bounded, plugin-owned translation catalogs and consume them through a
|
||||
host-scoped imperative/reactive localization API. Locale changes follow Kandev without bundling a
|
||||
second i18n runtime, and disable/reload/uninstall removes only that plugin's resources.
|
||||
|
||||
## Data model
|
||||
|
||||
@@ -118,6 +134,21 @@ capabilities:
|
||||
# "Frontend plugin runtime" and ADR
|
||||
# 2026-08-01-per-user-plugin-storage
|
||||
|
||||
actions:
|
||||
- key: "connection.save"
|
||||
scope: workspace # workspace | task | repository
|
||||
max_body_bytes: 65536
|
||||
|
||||
repository_providers: ["example-repository-provider"]
|
||||
|
||||
reference_sources:
|
||||
- source: "example_change_requests"
|
||||
provider: "example-repository-provider"
|
||||
kind: "change_request"
|
||||
display_name: "Example change requests"
|
||||
kind_label: "Change request"
|
||||
order: 100
|
||||
|
||||
webhooks:
|
||||
- key: "slack-events"
|
||||
description: "Slack Events API webhook"
|
||||
@@ -159,7 +190,7 @@ fields. Existing records without these fields load as null.
|
||||
`capabilities.api_read` / `capabilities.api_write` gate the **Host data API** Host
|
||||
RPCs (both reads and writes live now) — the vocabulary is a list of
|
||||
resource names: `tasks`, `sessions`, `messages`, `workspaces`, `workflows`,
|
||||
`agent_profiles`, `repositories` for `api_read`, plus `tasks` (CreateTask/
|
||||
`agent_profiles`, `executor_profiles`, `repositories` for `api_read`, plus `tasks` (CreateTask/
|
||||
UpdateTask) and `messages` (SendMessage) for `api_write`. See "Host data API".
|
||||
|
||||
**Declaring data access.** Listing a resource under `api_read` grants the
|
||||
@@ -174,6 +205,21 @@ not declared`. Writes work the same way under `api_write` (message
|
||||
independently on the same resource — a plugin may declare `api_read:tasks`
|
||||
without `api_write:tasks`, or vice versa (see "Host data API writes").
|
||||
|
||||
`actions` declare the only browser-invocable plugin operations. Each key is unique per
|
||||
plugin, has one resource scope (`workspace`, `task`, or `repository`), and supplies a
|
||||
bounded request-body maximum. `repository_providers` declares stable IDs the plugin may
|
||||
register in the frontend repository-provider registry; one enabled plugin owns one
|
||||
provider ID. A provider that supports the native task branch picker declares the
|
||||
workspace-scoped `repositories.branches` action. Kandev invokes it server-to-server with
|
||||
the persisted repository identity and accepts only a bounded normalized branch list;
|
||||
browser input cannot select the provider or repository for that invocation.
|
||||
`reference_sources` declares plugin-owned composer sources. Source names
|
||||
are unique, a descriptor cannot claim another provider, and all entries are removed when
|
||||
the plugin disables. See ADRs
|
||||
[2026-07-31-authenticated-plugin-actions](../../decisions/2026-07-31-authenticated-plugin-actions.md)
|
||||
and
|
||||
[2026-07-31-plugin-repository-provider-extensions](../../decisions/2026-07-31-plugin-repository-provider-extensions.md).
|
||||
|
||||
**External login (`auth`).** An `auth`-capable plugin can log a visitor in
|
||||
against an external IdP (OIDC/SAML): its webhook (the callback / SAML ACS)
|
||||
validates the token, then asserts the identity to kandev via the reserved
|
||||
@@ -192,8 +238,9 @@ See [ADR 0050](../../decisions/0050-plugin-external-auth-capability.md).
|
||||
There is no manifest-paste registration step. A plugin is installed from a URL or an
|
||||
uploaded tarball:
|
||||
|
||||
1. Operator calls `POST /api/plugins/install` with JSON `{"url": "..."}` (kandev
|
||||
downloads the tarball) or a multipart `package` field (direct upload).
|
||||
1. An administrator calls `POST /api/plugins/install` with JSON `{"url": "..."}`
|
||||
(kandev downloads the tarball) or a multipart `package` field (direct upload).
|
||||
Auth-disabled single-user instances retain their synthetic administrator.
|
||||
2. Kandev verifies `checksums.txt` covers every other file in the tarball and every
|
||||
hash matches (integrity gate, always enforced).
|
||||
3. If `checksums.txt.sig` is present, kandev verifies the ed25519 signature; if
|
||||
@@ -235,6 +282,10 @@ CREATE TABLE plugin_state (
|
||||
|
||||
### Plugin management API (operator -> kandev, HTTP)
|
||||
|
||||
Install is administrator-only when authentication is enabled. Auth-disabled
|
||||
single-user instances retain the synthetic administrator used by other system
|
||||
settings.
|
||||
|
||||
```
|
||||
POST /api/plugins/install # Install a plugin: JSON {"url": "..."} or multipart `package`
|
||||
POST /api/plugins/sync # Reconcile the registry with the plugins directory on disk
|
||||
@@ -249,6 +300,7 @@ POST /api/plugins/{id}/enable
|
||||
POST /api/plugins/{id}/disable
|
||||
GET /api/plugins/{id}/bundle # Frontend bundle, served from the extracted package dir
|
||||
GET /api/plugins/{id}/ui/* # Frontend bundle assets, served from the extracted package dir
|
||||
POST /api/plugins/{id}/actions/{key} # Authenticated declared browser action
|
||||
```
|
||||
|
||||
`POST /api/plugins/sync` is documented in full under "Filesystem sideloading & sync"
|
||||
@@ -263,6 +315,31 @@ Enable/disable/uninstall act on the supervised subprocess: disable stops it (sta
|
||||
config preserved); enable respawns it; uninstall stops it and deletes its package,
|
||||
record, and state.
|
||||
|
||||
### Authenticated plugin actions (browser -> kandev -> plugin)
|
||||
|
||||
`POST /api/plugins/{id}/actions/{key}` is the only browser action route. Kandev first
|
||||
applies ordinary HTTP authentication, then rejects inactive plugins or undeclared keys
|
||||
and authorizes every referenced workspace, task, or repository. It derives a task's
|
||||
workspace relation server-side, passes verified actor/resource context separately from
|
||||
bounded untrusted JSON, invokes `Plugin.HandleAction` with a hard timeout and
|
||||
cancellation, and relays only an allowlisted response-header set. Provider callback
|
||||
routes under `/webhooks/` stay public and must not serve authenticated browser actions.
|
||||
Task-scoped actions require a verified task and may optionally select one persisted
|
||||
repository attached to that task; Kandev rejects unattached repository IDs and passes
|
||||
the accepted repository separately in `VerifiedActionContext`.
|
||||
The manifest's canonical action field is `scope`; `resource_scope` remains a read-only
|
||||
compatibility alias for packages produced during the prerelease contract rollout.
|
||||
|
||||
### Dynamic composer reference sources (plugin -> kandev)
|
||||
|
||||
An active manifest `reference_sources` descriptor registers a plugin bridge in
|
||||
`internal/mentions`. Kandev calls `Plugin.SearchEntityReferences` with verified
|
||||
workspace, plain query, and bounded limit; plugin candidates are untrusted. The host
|
||||
injects descriptor identity and constructs canonical references. Kandev calls
|
||||
`Plugin.AuthorizeEntityReference` at search and again at message submission with
|
||||
purpose `search` or `submission`. A disabled plugin, invalid result, stale selection,
|
||||
or denial fails closed; no stale reference metadata enters the message queue.
|
||||
|
||||
### Event delivery (kandev -> plugin, gRPC `DeliverEvent`)
|
||||
|
||||
Kandev calls the plugin's `Plugin.DeliverEvent` RPC (unary) with an `Event` message:
|
||||
@@ -280,6 +357,7 @@ message Event {
|
||||
Expected response: `EventAck{}`. A non-nil gRPC error or a timeout counts as failure.
|
||||
|
||||
Delivery semantics (unchanged from earlier design, now carried over gRPC):
|
||||
|
||||
- **At-least-once.** Plugins must be idempotent (dedup by `event_id`).
|
||||
- **Timeout:** 10 seconds. Up to 3 retries with exponential backoff (5s, 15s, 45s).
|
||||
- **Sequential per plugin** — no concurrent delivery to the same plugin. Plugins
|
||||
@@ -292,14 +370,14 @@ Event types: any subject kandev publishes on its internal event bus
|
||||
below is a non-exhaustive sample across feature areas — the plugin system is not tied to
|
||||
any one of them.
|
||||
|
||||
| Category | Events |
|
||||
|----------|--------|
|
||||
| Tasks | `task.created`, `task.updated`, `task.state_changed`, `task.deleted`, `task.moved` |
|
||||
| Sessions | `task_session.state_changed`, `turn.started`, `turn.completed` |
|
||||
| Agents | `agent.started`, `agent.completed`, `agent.failed`, `agent.stopped` |
|
||||
| Category | Events |
|
||||
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Tasks | `task.created`, `task.updated`, `task.state_changed`, `task.deleted`, `task.moved` |
|
||||
| Sessions | `task_session.state_changed`, `turn.started`, `turn.completed` |
|
||||
| Agents | `agent.started`, `agent.completed`, `agent.failed`, `agent.stopped` |
|
||||
| Other feature areas (examples) | Any additional subjects emitted by feature areas such as office/agents (e.g. `office.comment.created`, `office.approval.created`) — plugins may subscribe to these, but the plugin system does not depend on them |
|
||||
| GitHub | `github.pr_state_changed`, `github.pr_feedback`, `github.new_issue` |
|
||||
| Plugin | `plugin.<plugin_id>.<name>` (cross-plugin events) |
|
||||
| GitHub | `github.pr_state_changed`, `github.pr_feedback`, `github.new_issue` |
|
||||
| Plugin | `plugin.<plugin_id>.<name>` (cross-plugin events) |
|
||||
|
||||
Wildcard subscriptions: `task.*`, `agent.*`, `<feature>.*` (any subject prefix).
|
||||
|
||||
@@ -427,17 +505,18 @@ domain structs. See [ADR 0043](../../decisions/0043-plugin-host-data-api.md) and
|
||||
|
||||
**Readable resources (v1).** Each is gated by an `api_read:<resource>` capability:
|
||||
|
||||
| RPC | Capability | Returns |
|
||||
|---|---|---|
|
||||
| `ListTasks` / `GetTask` | `api_read:tasks` | Tasks (id, workspace, workflow, title, description, state, priority, timestamps, parent, identifier, repositories, metadata) |
|
||||
| `ListWorkspaces` | `api_read:workspaces` | Workspaces (id, name, owner, defaults, timestamps) |
|
||||
| `ListWorkflows` | `api_read:workflows` | Workflows for a workspace |
|
||||
| `ListWorkflowSteps` | `api_read:workflows` | Steps for a workflow (id, name, position, stage type) |
|
||||
| `ListAgentProfiles` | `api_read:agent_profiles` | Agent profiles (id, agent id, display name, model, mode) |
|
||||
| `ListRepositories` | `api_read:repositories` | Repositories for a workspace (id, name, default branch) |
|
||||
| `ListSessions` | `api_read:sessions` | Session identity + agent context (id, task, agent profile, resolved display name + model, `acp_session_id`, state, timestamps) |
|
||||
| `ListSessionCodeStats` | `api_read:sessions` | **Computed** per-session code metrics: committed lines added/deleted, peak pending-diff lines added/deleted |
|
||||
| `ListMessages` | `api_read:messages` | Historical conversation content (id, session, task, turn, `author_type` (user/agent), `content`, `type`, `created_at`), filterable by session ids, task ids, a `created_at` range (`since`/`until`), and types. See "Conversation content" below. |
|
||||
| RPC | Capability | Returns |
|
||||
| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ListTasks` / `GetTask` | `api_read:tasks` | Tasks (id, workspace, workflow, title, description, state, priority, timestamps, parent, identifier, repositories, metadata) |
|
||||
| `ListWorkspaces` | `api_read:workspaces` | Workspaces (id, name, owner, defaults, timestamps) |
|
||||
| `ListWorkflows` | `api_read:workflows` | Workflows for a workspace |
|
||||
| `ListWorkflowSteps` | `api_read:workflows` | Steps for a workflow (id, name, position, stage type) |
|
||||
| `ListAgentProfiles` | `api_read:agent_profiles` | Agent profiles (id, agent id, display name, model, mode) |
|
||||
| `ListExecutorProfiles` | `api_read:executor_profiles` | Executor profiles (id, display name, executor type) |
|
||||
| `ListRepositories` | `api_read:repositories` | Repositories for a workspace (id, name, default branch) |
|
||||
| `ListSessions` | `api_read:sessions` | Session identity + agent context (id, task, agent profile, resolved display name + model, `acp_session_id`, state, timestamps) |
|
||||
| `ListSessionCodeStats` | `api_read:sessions` | **Computed** per-session code metrics: committed lines added/deleted, peak pending-diff lines added/deleted |
|
||||
| `ListMessages` | `api_read:messages` | Historical conversation content (id, session, task, turn, `author_type` (user/agent), `content`, `type`, `created_at`), filterable by session ids, task ids, a `created_at` range (`since`/`until`), and types. See "Conversation content" below. |
|
||||
|
||||
`acp_session_id` on a session is the external usage-attribution join key (e.g.
|
||||
`tokscale`): kandev exposes the session identity and code stats but stays out of
|
||||
@@ -478,7 +557,7 @@ missing task returns gRPC `NotFound`.
|
||||
`Host.Messages().Send` (capability `api_write:messages`) delivers a prompt to a
|
||||
task session through the orchestrator's real delivery path — the same one
|
||||
`message_task` uses — so the message reaches the agent and drives a turn (it is
|
||||
*not* an office comment). It resolves the target session (an explicit
|
||||
_not_ an office comment). It resolves the target session (an explicit
|
||||
`session_id`, verified to belong to the task, or the task's primary session),
|
||||
records a user message stamped with the plugin source, and dispatches by session
|
||||
state: a running session queues the prompt (`status: queued`); an idle/completed
|
||||
@@ -533,7 +612,7 @@ refreshes the list) reconciles the registry with whatever is actually on disk:
|
||||
registered and the others are reported as skipped, not registered.
|
||||
2. **Dropped tarballs.** Every `*.tar.gz` file sitting directly in the plugins
|
||||
directory is run through the same verified install pipeline `POST
|
||||
/api/plugins/install` uses (checksum verification, manifest validation, platform
|
||||
/api/plugins/install` uses (checksum verification, manifest validation, platform
|
||||
executable check, extraction, spawn, activate). On success the tarball file is
|
||||
deleted. On a validation failure the file is left in place (not retried
|
||||
automatically) and the failure is reported.
|
||||
@@ -572,17 +651,28 @@ Mattermost-webapp model), not iframes. The full contract lives in
|
||||
involved in serving these assets — the plugin subprocess only needs to be running
|
||||
to serve gRPC calls, not the UI bundle.
|
||||
- **Boot payload:** the SPA boot payload carries
|
||||
`plugins: [{ id, name, bundleUrl, styleUrls }]` for every **active** plugin that
|
||||
declares a bundle (gated on the `plugins` feature flag).
|
||||
`plugins: [{ id, name, bundleUrl, styleUrls, repositoryProviderIds? }]` for every
|
||||
**active** plugin that declares a bundle (gated on the `plugins` feature flag).
|
||||
`repositoryProviderIds` is the JSON projection of manifest
|
||||
`repository_providers`; before `initialize`, the loader supplies it to the registry
|
||||
as the plugin's provider/review ownership allowlist. Omission keeps older payloads
|
||||
compatible but grants no invented manifest declaration.
|
||||
- **Loading:** on boot (and on runtime enable), the frontend host dynamically
|
||||
`import()`s each `bundleUrl`. The bundle calls
|
||||
`window.registerKandevPlugin(id, { initialize(registry, host), destroy? })`.
|
||||
`host` shares the kandev React instance, the app store, a plugin-scoped
|
||||
`api.fetch`, a curated `@kandev/ui` subset, and the theme — so a plugin can build
|
||||
a page indistinguishable from first-party UI (e.g. a native `/jira` page).
|
||||
Activation is transactional: failure or timeout revokes every partial registration,
|
||||
aborts owned work, and fences callbacks that arrive after the attempt ended.
|
||||
- **Registry surface:** `registerRoute(path, C)`, `registerNavItem(item)`,
|
||||
`registerSettingsRoute(path, C)`, `registerComponent(slot, C)` (including
|
||||
`app-status-bar-left` and `app-status-bar-right`), `registerWsHandler(action, fn)`.
|
||||
`registerSettingsRoute(path, C)`,
|
||||
`registerIntegrationSettings({ id, label, description, icon?, Component })`,
|
||||
`registerComponent(slot, C)` (including `app-status-bar-left` and
|
||||
`app-status-bar-right`), and `registerWsHandler(action, fn)`. Integration-settings
|
||||
contributions appear in the native global integrations index, workspace settings
|
||||
navigation, and global/workspace settings routes. IDs are URL-safe, unique among
|
||||
active plugins, and cannot shadow host integrations; unload revokes the contribution.
|
||||
Status-slot components receive the exact `AppStatusBarSlotProps` contract in
|
||||
`PLUGIN-API.md`: current path/context plus placement and presentation. The host
|
||||
renders one responsive presentation at once — 24 px bar on tablet/desktop or
|
||||
@@ -602,16 +692,45 @@ Mattermost-webapp model), not iframes. The full contract lives in
|
||||
it globally, skipping editable targets the same way core app shortcuts do. User
|
||||
overrides are namespaced `plugin:{pluginId}:{id}` so they survive independently
|
||||
per plugin.
|
||||
- **Modals:** `host.openModal({ title?, content, size?, dismissible? })` imperatively
|
||||
opens a modal rendered by the host's `<PluginModalHost/>` (mounted once at the app
|
||||
root, isolated behind its own error boundary) and returns `{ close() }` to close
|
||||
- **Modals and drawers:** `host.openModal({ title?, description?, content, size?, dismissible?, presentation? })` imperatively
|
||||
opens a modal rendered by the host's `<PluginModalHost/>` (mounted once inside the
|
||||
authenticated `AppShell` theme/tooltip/toast provider tree and isolated behind its
|
||||
own error boundary) and returns `{ close() }` to close
|
||||
that instance. `content` reuses the slot-component contract (rendered with the
|
||||
host React instance). Independent of keybindings — any plugin code path may call
|
||||
it, including a keybinding handler.
|
||||
host React instance). `presentation: "drawer"` renders the contribution in a
|
||||
safe-area-aware host drawer for phone actions; omitted/`dialog` keeps desktop modal
|
||||
presentation. Independent of keybindings — any plugin code path may call it.
|
||||
- **Task change-request links:** `host.openTaskLinkDialog(...)` renders the same
|
||||
one-field dialog anatomy, inline validation, Cancel/Save footer, submitting state,
|
||||
success toast, and close behavior as Kandev's GitHub task-link flow. Code-host
|
||||
plugins supply provider copy and an authenticated
|
||||
`onSubmit(reference, signal)` callback; closing, unmounting, or revoking the plugin
|
||||
aborts that signal and suppresses late feedback;
|
||||
they do not build this workflow inside `openModal`. Link submenu children name only
|
||||
the target because the parent already supplies the verb.
|
||||
- **Provider registrations:** `registry.registerRepositoryProvider(...)` contributes
|
||||
repository listing, optional coarse URL matching, structured URL inspection, and
|
||||
branch listing. `matchesURL` is only a synchronous performance hint; workspace-scoped
|
||||
`inspectURL` is authoritative, returns `null` when the configured provider does not
|
||||
own the URL, and must produce exactly one winner across active providers. `inspectURL` returns
|
||||
a complete credential-free provider/repository/pull-request descriptor with an HTTPS
|
||||
clone URL. The host
|
||||
persists that descriptor rather than parsing plugin URLs. Once persisted, native task
|
||||
branch requests are routed to the active manifest owner through its declared
|
||||
workspace-scoped `repositories.branches` action using only that stored descriptor.
|
||||
`registerTaskAction(...)`
|
||||
contributes children of the native **Link** submenu with visibility and a read-only
|
||||
task/workspace/repository context. Unsupported top-level action placements are
|
||||
rejected at compile/registration time rather than accepted without a consumer.
|
||||
`registerReviewProvider(...)` supplies
|
||||
normalized review summaries, an external-store task-item source, and a plugin
|
||||
`ReviewPanel` rendered in native desktop/mobile review surfaces. All are
|
||||
manifest-owned, lifecycle-revocable registrations; duplicate active provider
|
||||
ownership is rejected.
|
||||
- **Task panels:** `registerTaskPanel({ id, title, icon?, Component, mobileEnabled? })`
|
||||
adds a row to the task workspace's "+" (add panel) menu; selecting it opens a
|
||||
dockview panel rendering `Component` with `{ panelId, taskId, sessionId,
|
||||
presentation }`. Every plugin panel shares one generic `"plugin-panel"` dockview
|
||||
presentation }`. Every plugin panel shares one generic `"plugin-panel"` dockview
|
||||
component (identity in `params.pluginId`/`params.panelKey`), so a saved layout
|
||||
round-trips even when the owning plugin is later uninstalled — the layout manager
|
||||
drops an unresolvable reference instead of throwing, and `Settings > Layouts`
|
||||
@@ -628,12 +747,12 @@ Mattermost-webapp model), not iframes. The full contract lives in
|
||||
the layout. Decision:
|
||||
ADR-2026-08-04-plugin-contribution-lifecycle-authority.
|
||||
- **Kanban card contributions:** `registerTaskMenuAction({ id, label, icon?,
|
||||
group: "edit", visible?, run })` adds an item to the kanban card's `Edit`
|
||||
group: "edit", visible?, run })` adds an item to the kanban card's `Edit`
|
||||
submenu (the flat `Edit` item becomes `Edit > Edit task` once any plugin
|
||||
registers one); `run(context)` receives `{ workspaceId, taskId, taskTitle,
|
||||
workflowStepId, presentation }`, and a rejected `run` is caught and logged
|
||||
workflowStepId, presentation }`, and a rejected `run` is caught and logged
|
||||
without blocking the menu from closing. `registerComponent("task-card-indicators",
|
||||
C)` renders `C` beside the PR status icon on every kanban card, receiving
|
||||
C)` renders `C` beside the PR status icon on every kanban card, receiving
|
||||
`{ taskId, workspaceId, workflowStepId }` as `slotProps`.
|
||||
`registerComponent("task-card-tags", C)` renders `C` in its own row on every
|
||||
kanban card (below the badges row), receiving the same
|
||||
@@ -661,13 +780,13 @@ error --successful Enable/health recovery--> active
|
||||
error --Disable--> disabled
|
||||
```
|
||||
|
||||
| State | Meaning |
|
||||
|---|---|
|
||||
| `registered` | Package extracted and record written; go-plugin spawn/handshake pending or in flight |
|
||||
| `active` | Handshake succeeded and health (`Ping`) passes; events delivered, webhooks proxied |
|
||||
| `error` | 3 consecutive `Ping` failures (30s interval, injectable), or the subprocess crashed and restart attempts (backoff, max 5) are exhausted. Events buffered (ring buffer, 100 events, 5-minute TTL). Webhooks return 503 |
|
||||
| `disabled` | Operator explicitly disabled. Subprocess stopped. No events, no webhooks. State and config preserved |
|
||||
| `uninstalled` | Subprocess stopped, package/record/state deleted (no grace period in v1) |
|
||||
| State | Meaning |
|
||||
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `registered` | Package extracted and record written; go-plugin spawn/handshake pending or in flight |
|
||||
| `active` | Handshake succeeded and health (`Ping`) passes; events delivered, webhooks proxied |
|
||||
| `error` | 3 consecutive `Ping` failures (30s interval, injectable), or the subprocess crashed and restart attempts (backoff, max 5) are exhausted. Events buffered (ring buffer, 100 events, 5-minute TTL). Webhooks return 503 |
|
||||
| `disabled` | Operator explicitly disabled. Subprocess stopped. No events, no webhooks. State and config preserved |
|
||||
| `uninstalled` | Subprocess stopped, package/record/state deleted (no grace period in v1) |
|
||||
|
||||
Health monitoring: kandev's go-plugin client calls `Ping()` on the plugin every 30
|
||||
seconds (injectable). 3 consecutive failures -> `error` + inbox item + restart attempt
|
||||
@@ -737,6 +856,13 @@ complete.
|
||||
- **External webhook hits a disabled/error plugin**: kandev returns 503.
|
||||
- **Undeclared capability access attempt on a Host RPC**: gRPC `PermissionDenied` with
|
||||
a message naming the missing capability.
|
||||
- **Undeclared, unauthorized, oversized, or timed-out browser action**: Kandev rejects
|
||||
it before/at bounded plugin dispatch; it never falls back to public webhook routing.
|
||||
- **Disabled/unloaded repository or review provider**: registrations and in-flight work
|
||||
are revoked; provider credential leases are invalidated immediately, and host
|
||||
selectors/panels remove stale plugin items safely, including after same-ID reload.
|
||||
- **Reference source denied during message submission**: Kandev rejects the selected
|
||||
reference rather than queuing stale or cross-workspace metadata.
|
||||
- **Checksum mismatch or unresolvable host-platform executable at install time**:
|
||||
install is rejected before any code runs.
|
||||
- **Frontend bundle import or initialization remains in flight**: open and saved
|
||||
@@ -901,6 +1027,37 @@ complete.
|
||||
a failed delivery leaves no durable user message and a retry can't duplicate
|
||||
the prompt.
|
||||
|
||||
- **GIVEN** an active plugin declares `connection.save` with workspace scope,
|
||||
**WHEN** a signed-in user invokes `host.api.invokeAction("connection.save", ...)`,
|
||||
**THEN** Kandev authenticates the caller, authorizes the workspace, bounds the
|
||||
payload, and passes verified context separately to `Plugin.HandleAction`; the public
|
||||
webhook endpoint is not invoked.
|
||||
|
||||
- **GIVEN** a provider operation owns an `AbortSignal`, **WHEN** its registration is
|
||||
replaced, unloaded, or its request is superseded, **THEN** `invokeAction` propagates
|
||||
cancellation to the authenticated HTTP request and backend action context.
|
||||
|
||||
- **GIVEN** a manifest-owned repository and review provider, **WHEN** it registers
|
||||
native task-link actions and a review panel, **THEN** Kandev renders those contributions
|
||||
in applicable desktop and mobile task/review surfaces and removes them, including
|
||||
in-flight work, when the plugin disables.
|
||||
|
||||
- **GIVEN** a registered review provider publishes normalized task status, **WHEN** a
|
||||
linked task renders on desktop or mobile, **THEN** Kandev automatically mounts the
|
||||
same topbar control, composer CI chip, hover popover/mobile drawer, review summary,
|
||||
comment summary, and checks anatomy used by GitHub, refreshes through the provider
|
||||
lifecycle, and requires no provider-owned visual slot or second poller.
|
||||
|
||||
- **GIVEN** a compatible code-host review provider, **WHEN** its panel renders normalized
|
||||
detail through `host.ui.ChangeRequestDetail`, **THEN** GitHub and the provider share
|
||||
the same header, collapsible sections, add-to-context controls, scroll ownership,
|
||||
loading/error treatment, and desktop/mobile geometry; only data, capabilities, and
|
||||
callbacks remain provider-owned.
|
||||
|
||||
- **GIVEN** a plugin-owned `#` reference source returns a pull-request candidate,
|
||||
**WHEN** the user submits the selected reference, **THEN** Kandev authorizes it
|
||||
again against the live plugin and rejects a disabled, stale, tampered, or
|
||||
cross-workspace candidate before queueing message metadata.
|
||||
- **GIVEN** a saved or open plugin task panel and a plugin reload whose import or
|
||||
`initialize()` takes longer than 500 milliseconds, **WHEN** registration eventually
|
||||
succeeds with the same panel identity, **THEN** the panel remains in the layout and
|
||||
@@ -953,10 +1110,10 @@ complete.
|
||||
in the kandev origin with full app-store access. Isolating plugin JS in a worker,
|
||||
realm, or comparable sandbox is future work; v1 relies on only loading active,
|
||||
operator-installed plugins served same-origin.
|
||||
- **In-process backend plugins.** Plugin *backends* remain out-of-process — no Go
|
||||
- **In-process backend plugins.** Plugin _backends_ remain out-of-process — no Go
|
||||
plugin loading via `plugin.Open`, no WASM, no shared-memory communication. (This is
|
||||
distinct from the frontend bundle, which does load into the SPA.)
|
||||
- **Plugin marketplace or registry.** Out of scope *for this spec*: this spec covers
|
||||
- **Plugin marketplace or registry.** Out of scope _for this spec_: this spec covers
|
||||
install-by-URL/upload as a manual, single-plugin action. The discoverable, curated
|
||||
catalog (central registry, one-click install, star ranking, third-party sources) is
|
||||
a sibling feature specified in [marketplace.md](marketplace.md) and built on top of
|
||||
|
||||
@@ -45,9 +45,10 @@ Decision: [ADR-2026-08-11-composer-access-authenticated-webhooks](../../decision
|
||||
authenticated webhook with a limit of at least 10 MiB.
|
||||
- The Voice plugin's OpenAI key belongs to its existing plugin settings and secret storage. Kandev
|
||||
relays the request but does not own, expose, or select that key.
|
||||
- Plugin localization is a separately scoped prerequisite. This package adds no host i18n API. The
|
||||
later Voice plugin task must decide how plugin-owned catalogs follow Kandev's locale before core
|
||||
Voice Mode is removed.
|
||||
- Plugin-owned copy uses the scoped catalog and reactive locale API established by
|
||||
[ADR-2026-08-12-plugin-localization-contract](../../decisions/2026-08-12-plugin-localization-contract.md).
|
||||
The later Voice plugin registers its English fallback and supported-locale catalogs before any
|
||||
composer contribution.
|
||||
- Disabling, uninstalling, or reloading a plugin aborts its in-flight webhook requests, unregisters
|
||||
its composer actions, and leaves native drafts intact.
|
||||
- The current core Voice Mode stays present until a separately delivered Voice plugin proves parity
|
||||
@@ -200,7 +201,6 @@ current external-call behavior. Request cancellation propagates through the exis
|
||||
- General authenticated REST routing, response streaming, bidirectional browser sockets, or changing
|
||||
the default limit for existing public webhooks.
|
||||
- Sandboxing mutually malicious native UI plugin bundles.
|
||||
- Plugin localization; it is a separate prerequisite for the later Voice plugin extraction.
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
|
||||