kandev/plugin-registry

Kandev plugin registry

This directory is the official Kandev marketplace source — the curated, PR-edited list of plugins and canvases that show up when a user opens Settings > Plugins > Browse inside Kandev.

It is deliberately minimal. It records which repositories are in the official catalog and registry-owned preview images. Release metadata (display name, description, author, version, tarball URL, package digest, stars) is read from the package and GitHub release when the catalog index is built.

Files

File	Purpose
plugins.yaml	The curated pointer list — one entry per plugin or canvas repo. Human-edited via PR.
schema.json	JSON Schema (draft 2020-12) that plugins.yaml MUST validate against. Enforced in CI.
build-index.mjs	Build script (zero-dependency Node) that resolves each entry to a full catalog record and emits index.json.
build-index.test.mjs	node --test coverage for the build script's parser and enrichment.

The generated index.json is published to GitHub Pages by the plugin-registry-index workflow and served as the fetch contract Kandev consumes.

One repository per plugin or canvas

Each plugin or canvas lives in its own public GitHub repository, named kdlbs/kandev-plugin-<name> for first-party plugins (third parties may use any owner/name). Every plugin repo publishes its package as a GitHub Release asset in the standard Kandev package format:

• <id>-<version>.tar.gz — the required plugin package. The archive contains its own generated checksums.txt, which the install pipeline verifies.
• checksums.txt — an optional release asset containing the tarball digest. The catalog does not currently populate or enforce it.

The kdlbs/kandev-plugin-template starter repo is the recommended way to bootstrap a new plugin with the right layout and a release workflow.

The catalog ranks plugins by GitHub stars (with a "recently updated" alternative from each repo's last release). Kandev collects no download or usage telemetry — there is no "most installed" metric, by design.

Submitting a plugin or canvas to the official catalog

1. Publish your plugin. Push it to a public GitHub repository and cut a GitHub Release whose assets include <id>-<version>.tar.gz. A separate release-level checksums.txt is optional; the package's internal generated checksum manifest is mandatory. The release must pass the standard package integrity gate.

2. Fork this repo (kdlbs/kandev).

3. Add one entry to plugin-registry/plugins.yaml pointing at your public repo. Native plugins keep the short form:

   - id: my-plugin            # MUST equal the `id` in your plugin manifest
     repo: your-org/your-plugin-repo
     categories: [productivity]
   

   A portable canvas declares its kind and at least one ordered preview. The first image is the catalog cover. Preview URLs are direct HTTPS image URLs and are not package files:

   - id: sprint-board
     repo: your-org/sprint-board
     kind: canvas
     categories: [productivity]
     previews:
       - url: https://cdn.example.com/sprint-board-cover.webp
         alt: Sprint board overview
   

   The id MUST match the id in your plugin manifest and be unique across the file. repo is owner/name. featured is a maintainer-only pin and should be left out of submissions.

4. Open a pull request. The index-build workflow runs on your PR (build + tests, no Pages deploy) and resolves your entry against the GitHub API — your repo must have a latest release that publishes a .tar.gz package; an entry whose repo has no release or no package is skipped. Name the package <id>-<version>.tar.gz and keep your entry id equal to your manifest id so the index resolves the right asset. plugins.yaml must also follow the schema.json pointer-list contract.

5. A maintainer reviews and merges — maintainer approval is what gates the official catalog. Once merged, the index-build workflow picks up your entry and your plugin or canvas appears in the in-app catalog on the next build. The canvas inspector validates the exact release asset, identity, source mode, permissions, and archive digest without executing package code.

Teams and corporates: host your own source instead

You do not have to PR into this registry to share plugins internally. Kandev supports additional marketplace sources: any URL that serves an index.json document of the same shape can be added under Settings > Plugins as an extra source, and its plugins are merged into the catalog alongside the official ones.

This is the recommended path for a team or corporate registry — host your own index.json (for example by copying this directory's plugins.yaml + build-index.mjs + workflow into your own repo and pointing Kandev at your Pages URL). Adding a source is an explicit act of trust in that source's maintainer, much like brew tap-ing a third-party tap. When the same id appears in more than one source, the official source wins and later duplicates are hidden.

Sideloading is always available

Appearing in this registry is only about discovery. Anyone can still install an unlisted plugin by URL or by uploading a .tar.gz directly — the marketplace never removes those escape hatches.