1a3c134f1a
Co-authored-by: Kandev Agent <agent@kandev.dev> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
386 lines
22 KiB
Markdown
386 lines
22 KiB
Markdown
---
|
|
status: building
|
|
created: 2026-07-18
|
|
owner: jcfs
|
|
---
|
|
|
|
# Plugin Marketplace
|
|
|
|
> **Implementation status (2026-07-18):** backend catalog + source store + HTTP
|
|
> API and the in-app Browse UI are implemented and unit/integration-tested; the
|
|
> git-hosted registry scaffolding (`plugin-registry/` + the index-build /
|
|
> star-refresh GitHub Actions) is committed. Remaining: a full browser E2E
|
|
> (needs a reachable fixture `index.json` + `KANDEV_PLUGIN_MARKETPLACE_URL`),
|
|
> and the four "Open questions" below (Pages domain, private-source auth,
|
|
> cross-source id collisions, provenance enforcement).
|
|
|
|
## Why
|
|
|
|
Today a user can only install a plugin if they already know its release tarball URL
|
|
or have a `.tar.gz` to upload (see [plugins spec](spec.md) → "Install pipeline").
|
|
There is no way to *discover* plugins from inside kandev, no curated list of what
|
|
exists, and no signal for which plugins are worth trusting. Plugin authors have
|
|
nowhere to publish, and teams have no sanctioned way to share an internal set of
|
|
plugins. This feature adds a discoverable, curated catalog — kandev's marketplace —
|
|
while keeping install-by-URL and sideloading as escape hatches.
|
|
|
|
## What
|
|
|
|
- Users SHALL be able to browse a catalog of available plugins from inside kandev
|
|
(Settings > Plugins > **Browse**) without knowing any URL in advance.
|
|
- The catalog SHALL be **searchable** (by name/description) and **filterable by
|
|
category**, and SHALL be **sorted by GitHub stars descending by default**. Stars are
|
|
a **sort hint, not a quality score** — no open-source first-party store actually
|
|
ranks by stars (Obsidian ranks by downloads), so the catalog SHOULD also expose
|
|
**"recently updated"** ordering (from each repo's last release / `pushed_at`) so new
|
|
or actively-maintained plugins are not buried under older high-star incumbents.
|
|
- Each catalog entry shows: display name, description, author, categories, the source
|
|
repository link, the latest published version, and its star count.
|
|
- Installing from the catalog SHALL be **one click**: it resolves to the plugin's
|
|
latest release tarball URL and runs the existing verified install pipeline
|
|
(`POST /api/plugins/install`). No new install mechanism is introduced.
|
|
- A catalog entry for a plugin that is already installed SHALL show an **Installed**
|
|
state; when the catalog's latest version is newer than the installed version, it
|
|
SHALL show an **Update available** affordance (which reinstalls the newer tarball).
|
|
- The catalog SHALL be assembled from **one or more marketplace sources**. kandev
|
|
ships with the **official kandev source** enabled by default; operators MAY add
|
|
**additional sources** (a team or corporate registry) and the catalog merges them.
|
|
- Ranking SHALL use **GitHub stars only**. kandev collects **no download or usage
|
|
telemetry** and exposes no "most installed" metric.
|
|
- The public registry is **curated**: a plugin appears in the official source only
|
|
after a maintainer-approved pull request adds it to the registry list. Anyone can
|
|
still install a non-listed plugin by URL/upload (sideloading is unaffected).
|
|
|
|
### Ecosystem shape (context, not a runtime contract)
|
|
|
|
The marketplace is backed by a git-hosted, PR-curated registry. The closest prior
|
|
art is **Obsidian's community plugins** (a central pointer list —
|
|
`community-plugins.json` — plus PR-to-add, with plugin code living in each author's
|
|
own GitHub releases), extended with **Homebrew's tap model** for third-party/corporate
|
|
sources and **`formulae.brew.sh`'s build pipeline** (a scheduled Action pulls the
|
|
source list, enriches it, emits a static JSON API, and serves it from GitHub Pages):
|
|
|
|
- **One Git repository per plugin** (`kdlbs/kandev-plugin-<name>`), each publishing
|
|
the plugin package as a GitHub **Release** asset in the existing
|
|
`<id>-<version>.tar.gz` format. A `kdlbs/kandev-plugin-template` starter repo is the
|
|
recommended way to bootstrap one.
|
|
- **The registry list** lives in the main kandev repo under `plugin-registry/`
|
|
(`plugins.yaml` + `schema.json`). It records *which repos* are in the official
|
|
catalog — not the plugin metadata itself, which is read from each plugin's own
|
|
release.
|
|
- **A GitHub Action builds `index.json`** from `plugins.yaml` (resolving each repo's
|
|
latest release, its manifest metadata, tarball URL + checksum, and current star
|
|
count) and publishes it to **GitHub Pages**. A scheduled run refreshes star counts.
|
|
- kandev fetches `index.json` — the official one plus any operator-added source URLs
|
|
pointing at the same-shaped document.
|
|
|
|
The per-repo publishing convention and the two Actions are an operational contract,
|
|
not a user-facing API; their normative shape is the `schema.json` and the
|
|
`index.json` document format defined under "Data model".
|
|
|
|
## Data model
|
|
|
|
### `plugins.yaml` (registry list — the curated, human-edited source of truth)
|
|
|
|
Lives at `plugin-registry/plugins.yaml` in the main kandev repo. A list of entries,
|
|
each pointing at one plugin repository. Deliberately minimal — descriptive metadata
|
|
is read from the plugin's own release manifest at build time so it can never drift
|
|
from what actually ships.
|
|
|
|
```yaml
|
|
plugins:
|
|
- id: agent-stats # MUST equal the plugin manifest `id`
|
|
repo: kdlbs/kandev-plugin-agent-stats # owner/name; the release source
|
|
# optional overrides / curation-only fields:
|
|
featured: false # maintainer may pin an entry above star order
|
|
```
|
|
|
|
Constraints:
|
|
- `id` unique across the file; MUST match the manifest `id` of the repo's latest
|
|
release (CI validates this).
|
|
- `repo` MUST be a resolvable `owner/name` with at least one release whose asset set
|
|
passes the existing package integrity gate (`checksums.txt`).
|
|
- The file MUST validate against `plugin-registry/schema.json` (enforced in CI on
|
|
every PR).
|
|
|
|
### `index.json` (generated catalog document — what kandev fetches)
|
|
|
|
Built from `plugins.yaml` by the index-build Action and served from GitHub Pages.
|
|
This is the fetch contract between a marketplace source and kandev. Additional
|
|
(corporate/team) sources MUST serve a document of this shape to be consumable.
|
|
|
|
```jsonc
|
|
{
|
|
"schema_version": 1,
|
|
"generated_at": "2026-07-18T10:00:00Z",
|
|
"source": { "name": "Kandev Official", "url": "https://<pages-host>/plugins/index.json" },
|
|
"plugins": [
|
|
{
|
|
"id": "agent-stats",
|
|
"name": "Agent Stats", // from manifest display_name
|
|
"description": "Per-session token & LOC dashboard",
|
|
"author": "kandev",
|
|
"categories": ["analytics"],
|
|
"icon_url": "https://raw.githubusercontent.com/kdlbs/kandev-plugin-agent-stats/v1.4.0/icon.svg",
|
|
"repo_url": "https://github.com/kdlbs/kandev-plugin-agent-stats",
|
|
"version": "1.4.0", // latest release
|
|
"min_kandev_version": "0.9.0", // from manifest, nullable
|
|
"package_url": "https://github.com/.../agent-stats-1.4.0.tar.gz",
|
|
"package_sha256": "…", // expected tarball digest (provenance)
|
|
"stars": 128, // GitHub stargazers at last refresh
|
|
"updated_at": "2026-07-17T12:00:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Constraints:
|
|
- `id` unique within a document. When the same `id` appears in more than one
|
|
configured source, the **first configured source wins** and later duplicates are
|
|
hidden (the official source is always first).
|
|
- `package_url` MUST point at a release asset in the existing package format.
|
|
- `icon_url`, when present, is an absolute URL to the plugin's icon (rendered on
|
|
the catalog card; the UI falls back to a letter tile when empty). It is
|
|
resolved by the index-build from the plugin manifest's optional `icon` field
|
|
(a package-relative path such as `icon.svg`) → a `raw.githubusercontent.com`
|
|
URL pinned to the release tag.
|
|
- `package_sha256`, when present, is the digest the client MAY use to confirm the
|
|
downloaded tarball matches what was curated, in addition to the package's own
|
|
internal `checksums.txt` gate.
|
|
|
|
### Marketplace sources (client-side configuration — SQLite)
|
|
|
|
The set of source documents kandev fetches. Stored as an application setting.
|
|
|
|
```
|
|
plugin_marketplace_source
|
|
id string PK
|
|
name string human label (e.g. "Acme Internal")
|
|
url string absolute URL of an index.json document
|
|
enabled bool default true
|
|
builtin bool true for the official source (present by default, not deletable)
|
|
created_at timestamp
|
|
```
|
|
|
|
The official source is seeded as a `builtin` row (its URL is a build/config
|
|
constant). Operators can add, enable/disable, and delete non-builtin sources.
|
|
|
|
## API surface
|
|
|
|
The catalog is fetched and merged **server-side** so that (a) cross-origin fetching
|
|
and per-source caching are handled in one place, (b) private corporate sources can
|
|
carry auth without exposing tokens to the browser, and (c) the "already installed /
|
|
update available" join against local records happens once. The browser talks only to
|
|
kandev; kandev talks to the source URLs.
|
|
|
|
```
|
|
GET /api/plugins/marketplace # Merged, deduped catalog across all enabled sources
|
|
# query: ?q=<search>&category=<cat>&sort=stars|name|recent
|
|
# stars (default): star count desc, unknown (null) last
|
|
# name: display name asc (case-insensitive)
|
|
# recent: updated_at desc (last release / repo push)
|
|
# each entry annotated with install_state:
|
|
# available | installed | update_available
|
|
GET /api/plugins/marketplace/sources # List configured sources
|
|
POST /api/plugins/marketplace/sources # Add a source {name, url}
|
|
PATCH /api/plugins/marketplace/sources/{id} # Enable/disable/rename a source
|
|
DELETE /api/plugins/marketplace/sources/{id} # Remove a non-builtin source
|
|
POST /api/plugins/marketplace/refresh # Force a re-fetch of all sources (bypass cache)
|
|
```
|
|
|
|
Installing from the catalog reuses the existing contract unchanged:
|
|
`POST /api/plugins/install` with `{"url": "<package_url>"}` (see
|
|
[plugins spec](spec.md) → "Plugin management API"). The marketplace endpoints are
|
|
read/config only; they never spawn or mutate a plugin process.
|
|
|
|
`GET /api/plugins/marketplace` responses are cached per source with a short TTL;
|
|
`refresh` and adding/removing a source invalidate the cache. A source that fails to
|
|
fetch or parse is reported as a degraded source in the response and its entries are
|
|
omitted — it never aborts the merge of the healthy sources.
|
|
|
|
## State machine
|
|
|
|
Catalog entries have a derived **install_state** computed by joining a catalog entry
|
|
against local plugin records (by `id`):
|
|
|
|
| install_state | condition |
|
|
|--------------------|-----------|
|
|
| `available` | no installed record with this `id` |
|
|
| `installed` | installed record exists, version ≥ catalog `version` |
|
|
| `update_available` | installed record exists, installed version < catalog `version` |
|
|
|
|
Installing an `available` entry, or updating an `update_available` one, both go
|
|
through `POST /api/plugins/install`; the plugin's own lifecycle
|
|
(`registered → active → error`, enable/disable/uninstall) is unchanged from the
|
|
[plugins spec](spec.md) → "State machine". The marketplace adds no new plugin states.
|
|
|
|
A **source** is `enabled` or `disabled`; only `enabled` sources contribute entries. A
|
|
transiently unreachable enabled source is surfaced as `degraded` in the catalog
|
|
response but stays `enabled`.
|
|
|
|
## Permissions
|
|
|
|
- Browsing the catalog and installing from it require the same operator authority as
|
|
the existing plugin-management API — marketplace endpoints sit behind the same
|
|
auth as `POST /api/plugins/install`. Plugins ship unflagged in the base
|
|
product, so there is no feature gate in front of either.
|
|
- Managing marketplace sources (add/remove/enable) is an operator action; adding a
|
|
source is an explicit act of trust in that source's maintainer, equivalent to
|
|
`brew tap`-ing a third-party tap.
|
|
- Appearing in the **official** source requires a maintainer to approve the
|
|
registry-list PR. Third-party/corporate sources are governed by whoever controls
|
|
that source repo, not by kandev.
|
|
|
|
## Failure modes
|
|
|
|
- **A source URL is unreachable or returns malformed JSON.** That source is marked
|
|
`degraded` in the `GET /api/plugins/marketplace` response, its entries are omitted,
|
|
and the healthy sources still return. No error is surfaced for the catalog as a
|
|
whole unless *every* source failed.
|
|
- **A catalog `package_url` 404s or the download fails at install time.** The
|
|
existing install pipeline surfaces the install error unchanged; the catalog entry
|
|
is unaffected.
|
|
- **`package_sha256` mismatch** between the catalog and the downloaded tarball:
|
|
once digest enforcement is enabled (a planned option — see "Open questions"),
|
|
install fails closed with a provenance error even though the tarball's own
|
|
`checksums.txt` may be internally consistent. In v1 the digest is advisory and
|
|
install proceeds through the existing pipeline unchanged.
|
|
- **Duplicate `id` across sources:** the first configured source wins; later
|
|
duplicates are silently hidden (documented, not an error).
|
|
- **GitHub star-refresh Action hits API rate limits:** the previous star counts in
|
|
`index.json` are retained (stale, not zeroed); the build must never publish `0`
|
|
stars for a repo it failed to query. (The Action should batch star lookups via the
|
|
GraphQL API under an authenticated PAT/App token — authenticated REST is 5,000
|
|
req/hr, unauthenticated only 60/hr, and the default `GITHUB_TOKEN` cannot reliably
|
|
read arbitrary external repos — so it stays well inside limits even as the list
|
|
grows.)
|
|
- **A listed repo deletes its latest release / the tarball asset:** the index-build
|
|
Action drops that entry (or keeps the last good version) and logs it; a plugin with
|
|
no installable release never appears with a dead `package_url`.
|
|
|
|
## Persistence guarantees
|
|
|
|
- Configured marketplace sources survive restart (SQLite).
|
|
- The fetched catalog is a **cache**, not durable state: it does not survive restart
|
|
and is re-fetched on demand. Star counts and versions are always as fresh as the
|
|
last successful source fetch, never authoritative locally.
|
|
- Installed plugins are unaffected by marketplace state — uninstalling every source,
|
|
or the official source going offline, never disables or removes an installed
|
|
plugin.
|
|
|
|
## Scenarios
|
|
|
|
- **GIVEN** the official source is reachable, **WHEN** the user opens Settings >
|
|
Plugins > Browse, **THEN** the plugins are listed sorted by star count descending,
|
|
each showing name, description, author, categories, version, and stars.
|
|
- **GIVEN** the catalog is showing, **WHEN** the user types a query, **THEN** only
|
|
entries whose name or description matches remain; **AND WHEN** the user picks a
|
|
category filter, **THEN** only entries in that category remain.
|
|
- **GIVEN** a catalog entry with `install_state: available`, **WHEN** the user clicks
|
|
Install, **THEN** kandev calls `POST /api/plugins/install` with the entry's
|
|
`package_url` and the plugin installs via the normal verified pipeline.
|
|
- **GIVEN** a plugin is already installed at the catalog's latest version, **WHEN**
|
|
the catalog renders, **THEN** its entry shows **Installed** and no Install button.
|
|
- **GIVEN** a plugin is installed at a version older than the catalog's, **WHEN** the
|
|
catalog renders, **THEN** its entry shows **Update available**, and clicking it
|
|
installs the newer tarball.
|
|
- **GIVEN** an operator adds a source `{name: "Acme Internal", url: …}`, **WHEN** the
|
|
catalog is next fetched, **THEN** Acme's plugins appear alongside the official ones,
|
|
and an Acme entry with an id that also exists in the official source is hidden in
|
|
favor of the official one.
|
|
- **GIVEN** a configured source is unreachable, **WHEN** the catalog is fetched,
|
|
**THEN** the response marks that source `degraded`, omits its entries, and still
|
|
returns entries from the reachable sources.
|
|
- **GIVEN** digest enforcement is enabled (planned) and a catalog entry whose
|
|
`package_sha256` does not match the downloaded tarball, **WHEN** the user installs
|
|
it, **THEN** the install fails closed with a provenance error and no plugin process
|
|
is spawned. (In v1 the digest is advisory; install is unchanged.)
|
|
- **GIVEN** the marketplace is empty or entirely offline, **WHEN** the user opens the
|
|
install dialog, **THEN** install-by-URL and upload still work exactly as before.
|
|
- **GIVEN** a PR that adds an entry to `plugins.yaml` whose `id` does not match the
|
|
target repo's latest-release manifest `id`, **WHEN** registry CI runs, **THEN** the
|
|
schema/consistency check fails and the PR is blocked.
|
|
|
|
## Auto-update (opt-in)
|
|
|
|
Beyond the manual **Update available** affordance, kandev can update installed
|
|
plugins in the background — **off by default, opt-in**. This does not add a new
|
|
install mechanism: an auto-update is exactly the existing verified reinstall of a
|
|
newer catalog `package_url` (`Service.InstallFromURL`), driven automatically
|
|
instead of by a click.
|
|
|
|
- **Two-tier toggle (Settings > Plugins).** An instance-wide **"Automatically
|
|
update plugins"** switch sets the default for every installed plugin. Each
|
|
plugin row also has its own switch that can **override** the default either way.
|
|
The effective setting is: per-plugin override when set, otherwise the
|
|
instance-wide default. A row shows an **override** badge and a **Reset** control
|
|
(clears the override → inherit the default again) whenever an explicit
|
|
per-plugin value is set. Both tiers persist across restart: the default in the
|
|
SQLite `plugin_settings` row, the per-plugin override in the plugin's stored
|
|
record (`auto_update`, carried forward verbatim on upgrade so an auto-update
|
|
never resets the toggle that triggered it).
|
|
- **Active plugins only.** A background poller (`AutoUpdatePoller`, ~90-minute
|
|
cadence, plus one sweep shortly after boot) upgrades a plugin only when it is
|
|
currently **active** *and* opted in *and* the catalog reports
|
|
`update_available`. **Disabled/errored plugins are never auto-updated** — a
|
|
disabled plugin stays on its installed version until re-enabled. Eligibility is
|
|
re-checked immediately before each install, so an operator who disables or
|
|
opts a plugin out mid-sweep is never overridden by a stale candidate.
|
|
- **Failure handling reuses the install pipeline unchanged.** An upgrade runs the
|
|
same verified path as a manual update: a package that fails its checksum/extract
|
|
gate is rejected with the installed version left untouched, and a package that
|
|
extracts but fails to spawn leaves the plugin in `error` (exactly as a manual
|
|
update would) rather than being silently reverted to the prior version — kandev
|
|
does not re-run a superseded release. A single plugin's failure is logged and
|
|
never aborts the rest of the sweep.
|
|
- **No new surface for the plugin itself.** Auto-update is an operator preference
|
|
layered over the existing install/lifecycle machinery; the plugin's own state
|
|
machine (`registered → active → disabled → error`) is unchanged.
|
|
|
|
API: `GET/PUT /api/plugins/settings` (`{auto_update_default}`) for the
|
|
instance-wide default and `PUT /api/plugins/:id/auto-update` (`{auto_update:
|
|
true|false|null}`) for the per-plugin override. Both require the same operator
|
|
authority as the rest of plugin management.
|
|
|
|
## Out of scope
|
|
|
|
- **Download / usage / install telemetry.** No counters, no "most installed", no
|
|
phone-home. Ranking is GitHub stars only. (Explicit product decision; revisit only
|
|
with opt-in telemetry — see the telemetry direction ADR/plan.)
|
|
- **Update channels / pinning.** Auto-update always tracks a source's latest
|
|
published version. There are no stable/beta channels, per-plugin version pins,
|
|
or scheduled maintenance windows — only the opt-in on/off toggles described in
|
|
"Auto-update (opt-in)" above.
|
|
- **Ratings, reviews, comments, or a paid/commercial plugin tier.**
|
|
- **A hosted web marketplace browse *site*.** GitHub Pages serves the `index.json`
|
|
document; a rich public browsing website is a later phase (the in-app catalog is the
|
|
v1 surface).
|
|
- **Signature *requirement*.** Package signing/provenance stays optional exactly as in
|
|
the [plugins spec](spec.md); the marketplace adds an *advisory* `package_sha256` but
|
|
does not make signing mandatory.
|
|
- **Runtime hardening / sandboxing of plugin JS.** Unchanged from the plugins spec;
|
|
the marketplace does not alter the trust boundary of an installed plugin.
|
|
|
|
## Open questions
|
|
|
|
- **Pages host / canonical official URL.** `kdlbs.github.io/kandev/plugins/index.json`
|
|
vs. a branded `plugins.kandev.*` domain — pick before wiring the builtin source
|
|
constant.
|
|
- **Private corporate sources & auth.** Do we support authenticated source URLs
|
|
(token/header) in v1, or only public `index.json` documents? Affects the source
|
|
data model (an optional credential ref) and the backend fetch.
|
|
- **Star refresh cadence & storage.** Confirm the schedule (daily?) and that star
|
|
counts live only in the generated `index.json` (not committed back to
|
|
`plugins.yaml`, to avoid noisy commits).
|
|
- **`package_sha256` provenance.** Confirm the index build pins the digest and the
|
|
client enforces it (recommended above) vs. relying solely on the package's internal
|
|
`checksums.txt`.
|
|
- **Cross-source id collisions.** v1 hides later-source duplicates (official wins). Do
|
|
we instead want Homebrew-style **fully-qualified `source/id`** names so a corporate
|
|
source can intentionally ship its own build of an official plugin without it being
|
|
silently hidden?
|
|
- **Anti-typosquatting / verified authorship.** Worth adopting Open VSX's
|
|
verified-namespace idea (a "verified" badge only when repo ownership is proven) and
|
|
cheap publish-time scans in the registry-validation Action (secret-leak / blocklist /
|
|
typosquat checks on the PR)? Deferred, but flagged as the natural next trust layer.
|