mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-10-10 17:16:36 +00:00

Files

T

ChuckandClaude Opus 5.5 db131e811b docs(store): describe the monorepo registry and the store UI as they are

- PLUGIN_STORE_GUIDE: the Plugin Store is a section of the Plugin
  Manager tab; URL installs are "Install from GitHub" -> "Install Single
  Plugin"; bulk update exists (Check & Update All) plus opt-in weekly
  auto-update; PluginStoreManager() defaults to plugins/, so the Python
  examples pass plugin-repos; registry plugins are downloaded (GitHub API,
  ZIP fallback), not cloned; updates compare version with latest_version.
- PLUGIN_REGISTRY_SETUP_GUIDE: replace the per-plugin-repo + tag
  walkthrough with a short page on the monorepo registry (plugin_path,
  latest_version, update_registry.py) that points at the monorepo's own
  SUBMISSION.md. Drops the reference to the deleted
  PLUGIN_IMPLEMENTATION_SUMMARY.md and setup_plugin_repos.py.
- plugin_registry_template.json: use the real entry shape.
- PLUGIN_QUICK_REFERENCE: automatic background updates exist (opt-in);
  registry example and publishing steps use the monorepo, not tags.
- PLUGIN_DEVELOPMENT_GUIDE: tags/releases are not read by the store.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-09-22 16:24:47 -04:00

4.1 KiB

Raw Blame History

Plugin Registry Setup Guide

This page explains how the official plugin registry works and how a plugin gets into it. The registry and the official plugins both live in one repository, ledmatrix-plugins; its SUBMISSION.md, VERIFICATION.md and docs/ are the authoritative contributor guides.

How it fits together

ledmatrix-plugins/
├── plugins/
│   ├── clock-simple/        # one directory per official plugin
│   │   ├── manifest.json    # source of truth for the plugin's version
│   │   ├── manager.py
│   │   ├── config_schema.json
│   │   └── requirements.txt
│   └── ...
├── plugins.json             # the registry the Plugin Store reads
└── update_registry.py       # regenerates plugins.json from the manifests

Registry. The Plugin Store fetches https://raw.githubusercontent.com/ChuckBuilds/ledmatrix-plugins/main/plugins.json (PluginStoreManager.REGISTRY_URL in src/plugin_system/store_manager.py) and caches it for 15 minutes.
Monorepo plugins have repo set to the ledmatrix-plugins URL and plugin_path set to their directory (plugins/<id>). The store downloads just that directory (GitHub API, falling back to the repository ZIP), so installed copies have no .git directory.
Third-party plugins keep their own repository: repo points at it and plugin_path is empty. The store installs them with git clone, falling back to an archive download.
Updates. For registry plugins the store compares the installed manifest's version with the entry's latest_version. Git tags and GitHub releases are not read.

A registry entry

{
  "id": "clock-simple",
  "name": "Simple Clock",
  "description": "A clean, simple clock display with date and time",
  "author": "ChuckBuilds",
  "category": "time",
  "tags": ["clock", "time", "date"],
  "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins",
  "branch": "main",
  "plugin_path": "plugins/clock-simple",
  "stars": 0,
  "downloads": 0,
  "last_updated": "2026-09-03",
  "verified": true,
  "screenshot": "",
  "latest_version": "1.0.0"
}

plugin_registry_template.json shows a monorepo entry and a third-party entry.

Don't edit latest_version or last_updated by hand for monorepo plugins: update_registry.py in ledmatrix-plugins writes them from each plugin's manifest.json.

Adding or changing an official plugin

Add or edit plugins/<your-plugin-id>/ in the monorepo. The store refuses a manifest without id, name, class_name and display_modes; also set version.
Bump version in the plugin's manifest.json for every change, or users won't be offered the update.
Run python update_registry.py in ledmatrix-plugins and commit the updated plugins.json with the plugin change.
Open a pull request. The monorepo's CI and review steps are described in its SUBMISSION.md.

Adding a third-party plugin

Test it with Plugin Manager → Install from GitHub → Install Single Plugin (or POST /api/v3/plugins/install-from-url), then follow the "own repository" option in the monorepo's SUBMISSION.md to request a registry entry.

Testing locally

# Validate a plugin headlessly (from LEDMatrix)
python3 scripts/check_plugin.py --plugin <id>

# Fetch the registry the way the store does
python3 -c "
from src.plugin_system.store_manager import PluginStoreManager
store = PluginStoreManager(plugins_dir='plugin-repos')
print(len(store.fetch_registry(force_refresh=True).get('plugins', [])), 'plugins')
"

To work on monorepo plugins against a LEDMatrix checkout, see MULTI_ROOT_WORKSPACE_SETUP.md and the Plugin Development Guide.

References

Plugin Store user guide: PLUGIN_STORE_GUIDE.md
Plugin architecture (historical): PLUGIN_ARCHITECTURE_SPEC.md
ledmatrix-plugins

4.1 KiB Raw Blame History