docs: flag aspirational/regressed features in plugin docs

These docs describe features that exist as documented in the doc but
either never wired up or regressed when v3 shipped. Each gets a clear
status banner so plugin authors don't waste time chasing features that
don't actually work.

FONT_MANAGER.md
- The "For Plugin Developers / Plugin Font Registration" section
  documents adding a "fonts" block to manifest.json that gets
  registered via FontManager.register_plugin_fonts(). The method
  exists at src/font_manager.py:150 but is **never called from
  anywhere** in the codebase (verified: zero callers). A plugin
  shipping a manifest "fonts" block has its fonts silently ignored.
  Added a status warning and a note about how to actually ship plugin
  fonts (regular files in the plugin dir, loaded directly).

PLUGIN_IMPLEMENTATION_SUMMARY.md
- Added a top-level status banner.
- Architecture diagram referenced src/plugin_system/registry_manager.py
  (which doesn't exist) and listed plugins/ as the install location.
  Replaced with the real file list (plugin_loader, schema_manager,
  health_monitor, operation_queue, state_manager) and pointed at
  plugin-repos/ as the default install location.
- "Dependency Management: Virtual Environments" — verified there's no
  per-plugin venv. Removed the bullet and added a note that plugin
  Python deps install into the system Python environment, with no
  conflict resolution.
- "Permission System: File Access Control / Network Access /
  Resource Limits / CPU and memory constraints" — none of these
  exist. There's a resource_monitor.py and health_monitor.py for
  metrics/warnings, but no hard caps or sandboxing. Replaced the
  section with what's actually implemented and a clear note that
  plugins run in the same process with full file/network access.

PLUGIN_CUSTOM_ICONS.md and PLUGIN_CUSTOM_ICONS_FEATURE.md
- The custom-icon feature was implemented in the v2 web interface
  via a getPluginIcon() helper in templates/index_v2.html that read
  the manifest "icon" field. When the v3 web interface was built,
  that helper wasn't ported. Verified in
  web_interface/templates/v3/base.html:515 and :774, plugin tab
  icons are hardcoded to `fas fa-puzzle-piece`. The "icon" field in
  plugin manifests is currently silently ignored (verified with grep
  across web_interface/ and src/plugin_system/ — zero non-action-
  related reads of plugin.icon or manifest.icon).
- Added a status banner to both docs noting the regression so plugin
  authors don't think their custom icons are broken in their own
  plugin code.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chuck
2026-04-07 09:39:46 -04:00
parent b577668568
commit a62d4529fb
4 changed files with 73 additions and 12 deletions

View File

@@ -1,5 +1,11 @@
# LEDMatrix Plugin System - Implementation Summary
> **Status note:** this is a high-level summary written during the
> initial plugin system rollout. Most of it is accurate, but a few
> sections describe features that are aspirational or only partially
> implemented (per-plugin virtual envs, resource limits, registry
> manager). Drift from current reality is called out inline.
This document provides a comprehensive overview of the plugin architecture implementation, consolidating details from multiple plugin-related implementation summaries.
## Executive Summary
@@ -14,16 +20,25 @@ The LEDMatrix plugin system transforms the project into a modular, extensible pl
LEDMatrix/
├── src/plugin_system/
│ ├── base_plugin.py # Plugin interface contract
│ ├── plugin_loader.py # Discovery + dynamic import
│ ├── plugin_manager.py # Lifecycle management
│ ├── store_manager.py # GitHub integration
── registry_manager.py # Plugin discovery
├── plugins/ # User-installed plugins
│ ├── store_manager.py # GitHub install / store integration
── schema_manager.py # Config schema validation
│ ├── health_monitor.py # Plugin health metrics
│ ├── operation_queue.py # Async install/update operations
│ └── state_manager.py # Persistent plugin state
├── plugin-repos/ # Default plugin install location
│ ├── football-scoreboard/
│ ├── ledmatrix-music/
│ └── ledmatrix-stocks/
└── config/config.json # Plugin configurations
```
> Earlier drafts of this doc referenced `registry_manager.py`. It was
> never created — discovery happens in `plugin_loader.py`. The earlier
> default plugin location of `plugins/` has been replaced with
> `plugin-repos/` (see `config/config.template.json:130`).
### Key Design Decisions
**Gradual Migration**: Plugin system added alongside existing managers
@@ -77,14 +92,26 @@ LEDMatrix/
- **Fallback System**: Default icons when custom ones unavailable
#### Dependency Management
- **Requirements.txt**: Per-plugin dependencies
- **Virtual Environments**: Isolated dependency management
- **Version Pinning**: Explicit version constraints
- **Requirements.txt**: Per-plugin dependencies, installed system-wide
via pip on first plugin load
- **Version Pinning**: Standard pip version constraints in
`requirements.txt`
#### Permission System
- **File Access Control**: Configurable file system permissions
- **Network Access**: Controlled API access
- **Resource Limits**: CPU and memory constraints
> Earlier plans called for per-plugin virtual environments. That isn't
> implemented — plugin Python deps install into the system Python
> environment (or whatever environment the LEDMatrix service is using).
> Conflicting versions across plugins are not auto-resolved.
#### Health monitoring
- **Resource Monitor** (`src/plugin_system/resource_monitor.py`): tracks
CPU and memory metrics per plugin and warns about slow plugins
- **Health Monitor** (`src/plugin_system/health_monitor.py`): tracks
plugin failures and last-success timestamps
> Earlier plans called for hard CPU/memory limits and a sandboxed
> permission system. Neither is implemented. Plugins run in the same
> process as the display loop with full file-system and network access
> — review third-party plugin code before installing.
## Plugin Development