João Salavisa
294 lines
20 KiB
Markdown
294 lines
20 KiB
Markdown
---
|
|
status: draft
|
|
system: plugins
|
|
requirements:
|
|
- REQ-PLUGINS-PLUGINS-001
|
|
created: 2026-04-26
|
|
owners:
|
|
- cfl
|
|
---
|
|
# Plugin System System Design Part 3
|
|
|
|
## Purpose and boundaries
|
|
|
|
This design preserves the technical source detail for `REQ-PLUGINS-PLUGINS-001` during migration.
|
|
|
|
## Requirement mapping
|
|
|
|
| Requirement | Design section |
|
|
| --- | --- |
|
|
| `REQ-PLUGINS-PLUGINS-001` | [Migrated source detail](#migrated-source-detail) |
|
|
|
|
## Migrated source detail
|
|
|
|
## Frontend plugin runtime (native JS UI plugins)
|
|
|
|
Plugins may extend the SPA with **native** React UI — routes, nav items, slot
|
|
components, and WebSocket handlers that run inside the kandev frontend (the
|
|
Mattermost-webapp model), not iframes. The full contract lives in
|
|
`docs/plans/plugins/PLUGIN-API.md`; summary:
|
|
|
|
- **Manifest:** a plugin declares `ui.bundle` (a root-relative path inside the
|
|
extracted package, e.g. `/ui/bundle.js`) and optional root-relative `ui.styles`.
|
|
- **Bundle delivery:** kandev serves the bundle at `GET /api/plugins/{id}/bundle`
|
|
(and any assets under `GET /api/plugins/{id}/ui/*`) directly from the extracted
|
|
package directory on local disk, forcing `Content-Type: text/javascript` and
|
|
stripping frame-blocking headers. No reverse proxy and no live upstream process are
|
|
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, 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)`,
|
|
`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. An optional integration action
|
|
receives the routed workspace and a `surface` value for the detail header or index
|
|
card. 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
|
|
phone Status drawer — so a plugin must tolerate remounting and adapt its own UI.
|
|
A status slot chooses the contribution's default side; portable user order may
|
|
move either contribution across the desktop spacer and determines drawer order.
|
|
Registrations are namespaced per plugin and bulk-revoked on disable/uninstall.
|
|
An exact plugin-detail settings route replaces the native detail content but
|
|
retains the host-owned personal shortcut card; nested settings routes remain
|
|
fully plugin-owned.
|
|
- **Isolation (v1):** only active, operator-installed plugins load; a failing
|
|
bundle/`initialize` is caught and never breaks boot; slot components render behind
|
|
error boundaries. Plugin JS otherwise runs with full in-origin store access —
|
|
hard sandboxing (workers/realms) is future work (see Out of scope).
|
|
- **Keybindings:** a plugin declares `ui.keybindings: [{ id, default, description }]`
|
|
in its manifest (`default` is a combo string like `mod+shift+k`, validated at
|
|
registration time). `registry.registerKeybinding(id, handler)` binds a JS handler
|
|
to a declared id; the host resolves the effective combo from the user's override
|
|
or the manifest `default` and dispatches 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. The
|
|
configuration location, user/operator boundary, and cross-surface conflict
|
|
behavior are governed by [Plugin Shortcut Settings](plugin-shortcut-settings.md).
|
|
- **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). `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
|
|
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`
|
|
renders a placeholder box for it. On phones, one bounded **Panels**
|
|
bottom-navigation entry opens a touch-native picker containing every
|
|
`mobileEnabled: true` registration; choosing one renders the same `Component`
|
|
full-height with `presentation: "mobile"`. Plugin loading and reloading are
|
|
authoritative lifecycle states, not elapsed-time guesses: a temporarily missing
|
|
registration never deletes an open or saved panel while its plugin is loading.
|
|
A successful initialization that omits a previously registered panel, or a
|
|
definitive disable/uninstall, closes that panel. If the removed panel is focused
|
|
on a phone, the session deterministically returns to Chat. A `Component` that
|
|
throws renders a per-panel error-boundary fallback without affecting the rest of
|
|
the layout. Decision:
|
|
ADR-2026-08-04-plugin-contribution-lifecycle-authority.
|
|
- **Task-menu and row contributions:** `registerTaskMenuAction({ id, label, icon?,
|
|
group: "edit" | "primary", visible?, run })` adds `"edit"` actions 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
|
|
without blocking the menu from closing. `"primary"` actions render on cards
|
|
and desktop/mobile task-row menus. `registerComponent("task-card-indicators",
|
|
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
|
|
`{ taskId, workspaceId, workflowStepId }` shape — for a contribution too wide
|
|
for the cramped title-row `task-card-indicators` spot, e.g. a row of tag chips.
|
|
`registerComponent("task-row-metadata", C)` renders plugin-agnostic,
|
|
read-only metadata on sidebar and `/tasks` rows. It receives
|
|
`{ taskId, workspaceId, workflowStepId, surface }`. An empty slot adds no
|
|
wrapper or spacing. Decision: ADR-2026-08-18-plugin-task-row-metadata.
|
|
- **Sidebar workspace actions:** `registerComponent("sidebar-workspace-actions", C)`
|
|
renders `C` after Quick Terminal/Quick Chat in the desktop sidebar's New Task
|
|
row and in the shared phone navigation sheet, forwarding
|
|
`{ workspaceId, workspaceLabel?, presentation }`. The host uses
|
|
`presentation: "desktop"` or `"mobile"`; mobile actions must expose a
|
|
touch-sized, accessible control.
|
|
- **`host.storage`:** authenticated, per-user key/value storage
|
|
(`get`/`set`/`delete`/`list`/`subscribe`), backed by the `plugin_user_state`
|
|
table (separate from the plugin-backend-only `plugin_state` table — no gRPC/proto
|
|
change) and requiring `capabilities.user_state: true`. A successful
|
|
`set`/`delete` publishes `plugin.user-state.updated` to the writing user's own
|
|
WS connections only (payload carries keys, never the value); `host.storage.subscribe`
|
|
filters to the plugin's own events and suppresses the writing tab's own echo via a
|
|
per-tab `writerId`. See `docs/decisions/2026-08-01-per-user-plugin-storage.md` and
|
|
the full contract in `PLUGIN-API.md`.
|
|
- **`host.ui.RichTextEditor` / `host.ui.RichTextReadOnly`:** narrow wrappers over the
|
|
Plan panel's tiptap markdown editor, pixel-identical to the Plan panel, so a
|
|
plugin needing rich text (e.g. a notes scratchpad) ships no tiptap of its own.
|
|
|
|
## State machine
|
|
|
|
```
|
|
registered -> active -> disabled -> uninstalled
|
|
registered|active|disabled --failure--> error
|
|
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) |
|
|
|
|
Health monitoring: kandev's go-plugin client calls `Ping()` on the plugin every 30
|
|
seconds (injectable). 3 consecutive failures -> `error` + inbox item + restart attempt
|
|
with backoff. A subprocess crash (unexpected process exit) triggers an immediate
|
|
restart with backoff (max 5 attempts, then `error`). Next successful handshake/`Ping`
|
|
-> `active`, queued events delivered in order, and the persisted failure diagnostic
|
|
is cleared. An operator can manually enable a plugin in `error` to retry its spawn
|
|
and handshake; boot does not automatically retry a persisted `error` state. A
|
|
manual Enable racing the final restart-exhaustion callback must complete without
|
|
deadlock: the manager never waits for a stopping process while holding its
|
|
process registry lock, so the final callback and replacement start can both
|
|
complete.
|
|
|
|
## Permissions
|
|
|
|
- Plugins are global to the kandev instance, installed by the operator. There is no per-user plugin access in v1.
|
|
- Capability-based access control: undeclared capabilities on a Host RPC return gRPC
|
|
status `PermissionDenied` with message `capability '<name>' not declared`.
|
|
- Each plugin's Host service instance is bound to its own plugin ID at spawn time —
|
|
there is no plugin-supplied ID to check, so capability checks evaluate directly
|
|
against that plugin's installed manifest on every RPC.
|
|
|
|
## Security
|
|
|
|
- **Auth is the spawn relationship.** Kandev spawns the plugin subprocess itself, so
|
|
there is no separate credential to issue, store, or leak: the go-plugin handshake
|
|
(magic cookie) plus AutoMTLS (mutual TLS negotiated per-launch, transparent to
|
|
plugin authors) authenticate the channel. There is no `api_key`, no
|
|
`webhook_secret`, and no HMAC signing anywhere in the contract.
|
|
- **Package integrity.** `checksums.txt` is verified for every file at install time.
|
|
An optional ed25519 signature (`checksums.txt.sig`) is verified when present;
|
|
unsigned packages install with a surfaced warning rather than being blocked (signing
|
|
is not required in v1 — see "Out of scope").
|
|
- **Capability-based access control** evaluated per Host RPC via a server interceptor.
|
|
- **Network**: the plugin subprocess talks to kandev over a unix domain socket
|
|
(macOS/Linux) or loopback TCP with AutoMTLS (Windows) — never a routable network
|
|
address. There is no remote/operator-hosted plugin tier in v1; every plugin backend
|
|
is a binary kandev spawns and supervises on the same host. See "Out of scope".
|
|
- **`host.storage`'s user-state routes are the first plugin HTTP surface reachable
|
|
with the caller's own browser session** (every other plugin HTTP route is either
|
|
operator-only management or a self-authenticating external webhook). It is
|
|
guarded the same way any other authenticated API route is — `httpmw`'s allowlist
|
|
explicitly does not cover it, so an unauthenticated request is rejected before the
|
|
handler runs — plus a capability gate (`user_state`), scope/key validation, a body
|
|
cap, and per-user row isolation. The stored value is opaque to the host: it is
|
|
never interpreted, never included in the `plugin.user-state.updated` WS payload,
|
|
and never delivered to the plugin's gRPC backend (a browser-only surface).
|
|
|
|
## Failure modes
|
|
|
|
- **3 consecutive `Ping` failures (90s), or crash with restart attempts exhausted
|
|
(max 5, backoff)**: status -> `error`. Events buffered (100, 5min TTL). Webhooks
|
|
return 503. Inbox item created and the bounded failure diagnostic is persisted
|
|
with its timestamp.
|
|
- **Failed spawn/handshake, missing install path, or failed restart**: status ->
|
|
`error` with the bounded diagnostic persisted; the Plugins UI exposes **Enable**
|
|
as the manual retry action.
|
|
- **Diagnostic safety**: persisted failure text is normalized, credential/path
|
|
redacted, and bounded before it is returned by plugin list/detail APIs. Plugin
|
|
stdout is not a durable diagnostic channel.
|
|
- **Buffer overflows (>100 events or >5min)**: oldest events dropped. Kandev emits
|
|
at most one overflow warning per plugin per minute, aggregating the number of
|
|
dropped events since the previous warning.
|
|
- **Plugin returns a gRPC error (or times out) on `DeliverEvent`**: retry up to 3 times
|
|
with exponential backoff (5s, 15s, 45s). After exhaustion, event is logged as failed
|
|
and dropped.
|
|
- **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
|
|
plugin-panel identities are preserved regardless of duration. A failed or timed-out
|
|
initialization leaves the panel recoverable for a later successful load; it is not
|
|
interpreted as disable or uninstall.
|
|
- **Per-user state purge fails during uninstall**: uninstall fails closed before the
|
|
package or plugin record is removed. The stopped-but-installed plugin remains
|
|
retryable and a successful retry purges every user's rows before removal completes.
|
|
|
|
## Persistence guarantees
|
|
|
|
- Plugin installation records (`id`, `version`, `install_path`, capabilities, status,
|
|
`signed`, `last_error`, `last_error_at`) persist to disk as
|
|
`~/.kandev/plugins/<id>.yml` and survive backend restarts.
|
|
- Extracted plugin packages persist at `~/.kandev/plugins/<id>/<version>/` until
|
|
uninstall.
|
|
- Plugin state in SQLite survives restarts.
|
|
- `plugin_user_state` survives restarts and ordinary disable/enable cycles, but no row
|
|
survives a successful uninstall. If its purge fails, uninstall does not report
|
|
success and leaves the plugin installed so the cleanup can be retried.
|
|
- Event delivery buffer is in-memory; events in the buffer do not survive a backend
|
|
restart.
|
|
- There are no plugin credentials to persist or lose — auth is re-derived from the
|
|
spawn relationship on every process launch.
|