docs: document the plugin marketplace
Add a public Plugin Marketplace page covering both audiences: operators using the in-app catalog (Browse/Installed tabs, one-click install, Update to vX, the Sources dialog for team/corporate registries, plugin icons, feature-flag gating, sideloading still works) and plugin authors publishing into it (one-repo-per-plugin GitHub Release assets, the optional manifest icon field, submitting a plugins.yaml PR to the official catalog, GitHub-stars-only ranking, and hosting your own index.json source). Also cross-link the new page from plugins.md (replacing the now-false "No plugin marketplace" security note), plugins-authoring.md, and plugins-manifest.md (new icon field row); register it in meta.json and coverage.json. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -273,6 +273,14 @@
|
||||
"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"]
|
||||
},
|
||||
{
|
||||
"id": "websocket-protocol",
|
||||
"audiences": ["contributor", "integrator"],
|
||||
|
||||
@@ -43,6 +43,7 @@
|
||||
"release-process",
|
||||
"---Plugins---",
|
||||
"plugins",
|
||||
"plugins-marketplace",
|
||||
"plugins-authoring",
|
||||
"plugins-manifest",
|
||||
"---Office---",
|
||||
|
||||
@@ -480,6 +480,18 @@ Install the resulting tarball via **Settings > Plugins** (upload) or:
|
||||
curl -F "package=@my-plugin-1.0.0.tar.gz" http://localhost:38429/api/plugins/install
|
||||
```
|
||||
|
||||
To show a custom card icon in the marketplace, ship an image in the package
|
||||
(e.g. `assets/icon.svg`) and point the manifest's [`icon`
|
||||
field](plugins-manifest.md#field-reference) at its package-relative path.
|
||||
|
||||
## Publishing to the marketplace
|
||||
|
||||
To make your plugin discoverable and one-click installable from inside kandev,
|
||||
publish the `<id>-<version>.tar.gz` + `checksums.txt` as a GitHub **Release**
|
||||
asset and either open a PR listing your repo in the official catalog or host
|
||||
your own source. See [Plugin marketplace →
|
||||
Publishing](plugins-marketplace.md#publishing-a-plugin).
|
||||
|
||||
## Iterate loop
|
||||
|
||||
- **UI-only or backend-only change:** edit the source, repackage
|
||||
|
||||
@@ -71,6 +71,7 @@ ui: # optional native frontend plugin
|
||||
| `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. |
|
||||
| `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 | Optional advisory; not currently enforced by the installer. |
|
||||
|
||||
@@ -0,0 +1,180 @@
|
||||
---
|
||||
title: "Plugin Marketplace"
|
||||
description: "Discover and install kandev plugins from the in-app catalog, keep them updated, add a team or corporate source, and publish your own plugin to the official catalog."
|
||||
status: experimental
|
||||
---
|
||||
|
||||
# Plugin Marketplace
|
||||
|
||||
The marketplace is a discoverable, curated catalog of kandev plugins you can
|
||||
browse and install from inside the app — no tarball URL required. It is
|
||||
assembled from one or more **sources**: kandev ships with the official source
|
||||
enabled by default, and you can add team or corporate sources alongside it.
|
||||
|
||||
This page covers using the marketplace (browse, install, update, add sources)
|
||||
and publishing a plugin into it. For what plugins are and how the install
|
||||
pipeline, enable/disable, and security posture work, see
|
||||
[Plugins](plugins.md). For building one, see [Authoring a
|
||||
plugin](plugins-authoring.md).
|
||||
|
||||
Like the rest of plugins, the marketplace is gated behind the `plugins` feature
|
||||
flag (**Settings > System > Feature Toggles**) — off by default in production,
|
||||
on by default in dev/e2e builds. Enabling it requires a backend restart and
|
||||
surfaces **Settings > Plugins** in the sidebar.
|
||||
|
||||
> **Sideloading still works.** The marketplace only adds *discovery*. Installing
|
||||
> a plugin by URL or by uploading a `.tar.gz` is unchanged and always available,
|
||||
> even with every source disabled or offline — see
|
||||
> [Plugins → Installing a plugin](plugins.md#installing-a-plugin).
|
||||
|
||||
## Using the marketplace
|
||||
|
||||
**Settings > Plugins** has two tabs:
|
||||
|
||||
- **Installed** — the plugins on this instance, with Enable / Disable /
|
||||
Uninstall and an **Update** button when a newer version is available.
|
||||
- **Browse** — the merged catalog across all enabled sources.
|
||||
|
||||
### Browse and install
|
||||
|
||||
Open **Settings > Plugins > Browse**. Each plugin shows as a card with its
|
||||
name, description, author, categories, source repository link, latest version,
|
||||
and GitHub star count. To narrow the list:
|
||||
|
||||
- **Search** — type in the search box to match plugin name or description.
|
||||
- **Category** — filter to a single category with the category dropdown.
|
||||
- **Sort** — **Most stars** (default), **Recently updated** (by latest release
|
||||
/ repo activity), or **Name**.
|
||||
|
||||
Stars are a **sort hint, not a quality score**. kandev collects no download or
|
||||
usage telemetry, so there is no "most installed" metric — ranking is GitHub
|
||||
stars only, and "Recently updated" surfaces new or actively maintained plugins
|
||||
that high-star incumbents would otherwise bury.
|
||||
|
||||
Click **Install** on a card to install it. This resolves the entry to its
|
||||
latest release tarball and runs the same verified install pipeline as
|
||||
install-by-URL (`POST /api/plugins/install`) — see [Plugins → Installing a
|
||||
plugin](plugins.md#installing-a-plugin) for the exact steps and integrity
|
||||
checks. A card for a plugin you already have at the latest version shows
|
||||
**Installed** instead of an install button.
|
||||
|
||||
Plugin-provided icons render on the cards. A plugin that ships an icon (via the
|
||||
manifest's `icon` field) shows it; otherwise the card falls back to a neutral
|
||||
letter tile.
|
||||
|
||||
### Keep plugins updated
|
||||
|
||||
When the marketplace advertises a newer version than the one you have
|
||||
installed, the **Installed** tab shows an **Update to v`<version>`** button on
|
||||
that plugin's row. Clicking it reinstalls the newer tarball through the normal
|
||||
pipeline; Enable, Disable, and Uninstall are unchanged.
|
||||
|
||||
Updates are never automatic — kandev surfaces the newer version and waits for
|
||||
an explicit click. There are no update channels and no background auto-update.
|
||||
|
||||
### Add a team or corporate source
|
||||
|
||||
The **Sources** button on the Browse tab opens the **Marketplace sources**
|
||||
dialog. The official kandev source is present by default, badged **Official**,
|
||||
and cannot be removed. To add another:
|
||||
|
||||
1. Click **Sources**.
|
||||
2. Enter a **name** (e.g. `Acme Internal`) and the **URL** of an `index.json`
|
||||
document (see [Host your own source](#host-your-own-source) below).
|
||||
3. Click **Add**.
|
||||
|
||||
Its plugins are then merged into the Browse tab alongside the official ones.
|
||||
You can enable/disable a source without deleting it, and remove any non-official
|
||||
source. Adding a source is an explicit act of trust in its maintainer, much
|
||||
like `brew tap`-ing a third-party tap.
|
||||
|
||||
Notes:
|
||||
|
||||
- When the same plugin `id` appears in more than one source, the **first
|
||||
configured source wins** (the official source is always first); later
|
||||
duplicates are hidden.
|
||||
- A source that is unreachable or serves malformed JSON is reported as
|
||||
**degraded** — its entries are omitted, but the healthy sources still load.
|
||||
- Configured sources persist across restarts; the fetched catalog itself is a
|
||||
short-lived cache and is re-fetched on demand.
|
||||
|
||||
## Publishing a plugin
|
||||
|
||||
Getting a plugin into the catalog follows a **one-repo-per-plugin** model,
|
||||
mirroring Obsidian's community-plugin registry: each plugin lives in its own
|
||||
public GitHub repository and publishes its package as a GitHub **Release**
|
||||
asset; the official catalog is a curated pointer list that names *which repos*
|
||||
are included. The descriptive metadata (name, description, version, tarball
|
||||
URL, stars) is always read from your latest release, so a listing can never
|
||||
drift from what actually ships.
|
||||
|
||||
### 1. Publish the plugin package as a release
|
||||
|
||||
Package your plugin as usual (see [Authoring a plugin →
|
||||
Packaging](plugins-authoring.md#packaging)) and cut a GitHub **Release** whose
|
||||
assets include both:
|
||||
|
||||
- `<id>-<version>.tar.gz` — the plugin package, and
|
||||
- `checksums.txt` — the integrity manifest the install pipeline verifies.
|
||||
|
||||
The release must pass the standard package integrity gate. The
|
||||
`kdlbs/kandev-plugin-template` starter repo is the recommended way to bootstrap
|
||||
a repo with the right layout and a release workflow.
|
||||
|
||||
### 2. Add an icon (optional)
|
||||
|
||||
Add an `icon:` field to your `manifest.yaml` — a **package-relative path** to an
|
||||
image your package ships (for example `icon.svg`). The catalog resolves it to
|
||||
your icon and renders it on the plugin card; without it, the card shows a letter
|
||||
tile. See the [Plugin manifest reference](plugins-manifest.md#field-reference).
|
||||
|
||||
### 3. Submit to the official catalog
|
||||
|
||||
The official source is curated: a plugin appears only after a maintainer merges
|
||||
a PR that lists it.
|
||||
|
||||
1. Fork `kdlbs/kandev` and add one entry to
|
||||
[`plugin-registry/plugins.yaml`](https://github.com/kdlbs/kandev/blob/main/plugin-registry/plugins.yaml)
|
||||
pointing at your public repo:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
- id: my-plugin # MUST equal the `id` in your plugin manifest
|
||||
repo: your-org/your-plugin-repo # owner/name
|
||||
categories: [productivity] # optional
|
||||
```
|
||||
|
||||
`id` must match your manifest `id` and be unique in the file. `featured` is a
|
||||
maintainer-only pin — leave it out of submissions.
|
||||
2. Open a pull request. CI validates `plugins.yaml` against
|
||||
[`plugin-registry/schema.json`](https://github.com/kdlbs/kandev/blob/main/plugin-registry/schema.json)
|
||||
and checks that your `id` matches your repo's latest-release manifest `id`.
|
||||
3. A maintainer reviews and merges. The index-build workflow picks up your entry
|
||||
and your plugin appears in the in-app catalog on the next build.
|
||||
|
||||
Ranking in the catalog is **GitHub stars only** — there is no download or usage
|
||||
telemetry to game. Full submission details are in
|
||||
[`plugin-registry/README.md`](https://github.com/kdlbs/kandev/blob/main/plugin-registry/README.md).
|
||||
|
||||
## Host your own source
|
||||
|
||||
You do not have to PR into the official registry to share plugins internally.
|
||||
Any URL that serves an `index.json` document of the catalog shape can be added
|
||||
as a marketplace source (see [Add a team or corporate
|
||||
source](#add-a-team-or-corporate-source)), and its plugins merge into the Browse
|
||||
tab alongside the official ones. This is the recommended path for a team or
|
||||
corporate registry — no PR to the main repo.
|
||||
|
||||
The `index.json` document is the fetch contract between a source and kandev. The
|
||||
simplest way to produce one is to copy the official registry's
|
||||
`plugin-registry/` directory into your own repo — its `plugins.yaml` +
|
||||
[`build-index.mjs`](https://github.com/kdlbs/kandev/blob/main/plugin-registry/build-index.mjs)
|
||||
build script (zero-dependency Node) + GitHub Action resolve each listed repo's
|
||||
latest release into a full catalog record and publish the generated
|
||||
`index.json` to GitHub Pages. Point kandev at that Pages URL. The document
|
||||
shape, the build pipeline, and the source data model are specified in the
|
||||
[plugin marketplace spec](https://github.com/kdlbs/kandev/blob/main/docs/specs/plugins/marketplace.md).
|
||||
|
||||
Related: [Plugins](plugins.md), [Authoring a
|
||||
plugin](plugins-authoring.md), [Plugin manifest
|
||||
reference](plugins-manifest.md).
|
||||
+18
-10
@@ -10,9 +10,10 @@ Plugins extend kandev without forking core: a plugin ships a **Go backend**
|
||||
that kandev spawns and supervises as a subprocess over a strict typed gRPC
|
||||
protocol, and can optionally ship a **native frontend bundle** that kandev
|
||||
loads into the SPA. This page covers what plugins are, how to install and
|
||||
manage them, and the current security posture. For building a plugin, see
|
||||
[Authoring a plugin](plugins-authoring.md). For the manifest schema, see
|
||||
[Plugin manifest reference](plugins-manifest.md).
|
||||
manage them, and the current security posture. To discover and install plugins
|
||||
from the in-app catalog, see the [Plugin marketplace](plugins-marketplace.md).
|
||||
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 are gated behind the `plugins` feature flag
|
||||
@@ -41,10 +42,14 @@ its own action right where you message an agent.
|
||||
|
||||
## Installing a plugin
|
||||
|
||||
Open **Settings > Plugins** and click **Install plugin**. You can install
|
||||
from a URL (kandev downloads the tarball) or by uploading a `.tar.gz` file
|
||||
directly. No credentials are ever shown or copied — installing a plugin has
|
||||
nothing to reveal, unlike a webhook-secret/API-key registration flow.
|
||||
The easiest way to install is from the in-app catalog — **Settings > Plugins >
|
||||
Browse**, then **Install** on a card (see the [Plugin
|
||||
marketplace](plugins-marketplace.md)). To install a plugin that is not in a
|
||||
configured catalog, open **Settings > Plugins** and click **Install plugin**.
|
||||
You can install from a URL (kandev downloads the tarball) or by uploading a
|
||||
`.tar.gz` file directly. No credentials are ever shown or copied — installing a
|
||||
plugin has nothing to reveal, unlike a webhook-secret/API-key registration
|
||||
flow.
|
||||
|
||||

|
||||
|
||||
@@ -188,9 +193,12 @@ identically to an unsigned one; signing is not required in v1.
|
||||
realm boundary) is explicit future work — see below.
|
||||
- **Package integrity is always checked; signing is optional.** See
|
||||
"Signed vs. unsigned packages" above.
|
||||
- **No plugin marketplace.** Install-by-URL/upload is a manual, single-plugin
|
||||
action; there is no central catalog, one-click install, or automatic
|
||||
discovery.
|
||||
- **Curated marketplace, no auto-install.** The [Plugin
|
||||
marketplace](plugins-marketplace.md) adds one-click install from a catalog,
|
||||
but the official source is PR-curated (a plugin appears only after a
|
||||
maintainer approves it), install is always an explicit operator action, and
|
||||
updates require an explicit click — there is no automatic discovery or
|
||||
background install. kandev collects no download or usage telemetry.
|
||||
|
||||
Related: [Authoring a plugin](plugins-authoring.md), [Plugin manifest
|
||||
reference](plugins-manifest.md), and [Extending Kandev](extending-kandev.md).
|
||||
|
||||
Reference in New Issue
Block a user