# 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`](../.github/workflows/plugin-registry-index.yml)
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:

   ```yaml
   - 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:

   ```yaml
   - 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.