From b5776685682f6099175ff3a4c6a9d5d8481a8778 Mon Sep 17 00:00:00 2001 From: Chuck Date: Tue, 7 Apr 2026 09:25:01 -0400 Subject: [PATCH] docs: clarify plugin paths and fix systemd manual install bug MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PLUGIN_DEVELOPMENT_GUIDE.md - Added a "Plugin directory note" callout near the top explaining the plugins/ vs plugin-repos/ split: - Dev workflow uses plugins/ (where dev_plugin_setup.sh creates symlinks) - Production / Plugin Store uses plugin-repos/ (the configurable default per config.template.json:130) - The plugin loader falls back to plugins/ so dev symlinks are picked up automatically (schema_manager.py:77) - User can set plugins_directory to "plugins" in the General tab if they want both to share a directory CLAUDE.md - The Project Structure section had plugins/ and plugin-repos/ exactly reversed: - Old: "plugins/ - Installed plugins directory (gitignored)" "plugin-repos/ - Development symlinks to monorepo plugin dirs" - Real: plugin-repos/ is the canonical Plugin Store install location and is not gitignored. plugins/* IS gitignored (verified in .gitignore) and is the legacy/dev location used by scripts/dev/dev_plugin_setup.sh. Reversed the descriptions and added line refs. systemd/README.md - "Manual Installation" section told users to copy the unit file directly to /etc/systemd/system/. Verified the unit file in systemd/ledmatrix.service contains __PROJECT_ROOT_DIR__ placeholders that the install scripts substitute at install time. A user following the manual steps would get a service that fails to start with "WorkingDirectory=__PROJECT_ROOT_DIR__" errors. Added a clear warning and a sed snippet that substitutes the placeholder before installing. src/common/README.md - Was missing 2 of the 11 utility modules in the directory (verified with ls): permission_utils.py and cli.py. Added brief descriptions for both. Out-of-scope code bug found while auditing (flagged but not fixed): - scripts/dev/dev_plugin_setup.sh:9 sets PROJECT_ROOT="$SCRIPT_DIR" which resolves to scripts/dev/, not the project root. This means the script's PLUGINS_DIR resolves to scripts/dev/plugins/ instead of the project's plugins/ — confirmed by the existence of scripts/dev/plugins/of-the-day/ from prior runs. Real fix is to set PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)". Not fixing in this docs PR. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 10 ++++++++-- docs/PLUGIN_DEVELOPMENT_GUIDE.md | 9 +++++++++ src/common/README.md | 11 +++++++++++ systemd/README.md | 31 +++++++++++++++++++++++-------- 4 files changed, 51 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 61b77500..e5930fdd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,8 +4,14 @@ - `src/plugin_system/` — Plugin loader, manager, store manager, base plugin class - `web_interface/` — Flask web UI (blueprints, templates, static JS) - `config/config.json` — User plugin configuration (persists across plugin reinstalls) -- `plugins/` — Installed plugins directory (gitignored) -- `plugin-repos/` — Development symlinks to monorepo plugin dirs +- `plugin-repos/` — **Default** plugin install directory used by the + Plugin Store, set by `plugin_system.plugins_directory` in + `config.json` (default per `config/config.template.json:130`). + Not gitignored. +- `plugins/` — Legacy/dev plugin location. Gitignored (`plugins/*`). + Used by `scripts/dev/dev_plugin_setup.sh` for symlinks. The plugin + loader falls back to it when something isn't found in `plugin-repos/` + (`src/plugin_system/schema_manager.py:77`). ## Plugin System - Plugins inherit from `BasePlugin` in `src/plugin_system/base_plugin.py` diff --git a/docs/PLUGIN_DEVELOPMENT_GUIDE.md b/docs/PLUGIN_DEVELOPMENT_GUIDE.md index 5315bbe1..e368bd62 100644 --- a/docs/PLUGIN_DEVELOPMENT_GUIDE.md +++ b/docs/PLUGIN_DEVELOPMENT_GUIDE.md @@ -12,6 +12,15 @@ When developing plugins in separate repositories, you need a way to: The solution uses **symbolic links** to connect plugin repositories to the `plugins/` directory, combined with a helper script to manage the linking process. +> **Plugin directory note:** the dev workflow described here puts +> symlinks in `plugins/`. The plugin loader's *production* default is +> `plugin-repos/` (set by `plugin_system.plugins_directory` in +> `config.json`), but it falls back to `plugins/` so the dev symlinks +> are picked up automatically. The Plugin Store installs to +> `plugin-repos/`. If you want both your dev symlinks *and* store +> installs to share the same directory, set `plugins_directory` to +> `plugins` in the General tab of the web UI. + ## Quick Start ### 1. Link a Plugin from GitHub diff --git a/src/common/README.md b/src/common/README.md index f381614e..4f9b0b6b 100644 --- a/src/common/README.md +++ b/src/common/README.md @@ -71,6 +71,17 @@ General-purpose utility functions: - Boolean parsing - Logger creation (deprecated - use `src.logging_config.get_logger()`) +## Permission Utilities (`permission_utils.py`) + +Helpers for ensuring directory permissions and ownership are correct +when running as a service (used by `CacheManager` to set up its +persistent cache directory). + +## CLI Helpers (`cli.py`) + +Shared CLI argument parsing helpers used by `scripts/dev/*` and other +command-line entry points. + ## Best Practices 1. **Use centralized logging**: Import from `src.logging_config` instead of creating loggers directly diff --git a/systemd/README.md b/systemd/README.md index 2e638e82..a2408954 100644 --- a/systemd/README.md +++ b/systemd/README.md @@ -28,14 +28,29 @@ These service files are installed by the installation scripts in `scripts/instal ## Manual Installation -If you need to install a service manually: - -```bash -sudo cp systemd/ledmatrix.service /etc/systemd/system/ -sudo systemctl daemon-reload -sudo systemctl enable ledmatrix.service -sudo systemctl start ledmatrix.service -``` +> **Important:** the unit files in this directory contain +> `__PROJECT_ROOT_DIR__` placeholders that the install scripts replace +> with the actual project directory at install time. Do **not** copy +> them directly to `/etc/systemd/system/` — the service will fail to +> start with `WorkingDirectory=__PROJECT_ROOT_DIR__` errors. +> +> Always install via the helper script: +> +> ```bash +> sudo ./scripts/install/install_service.sh +> ``` +> +> If you really need to do it by hand, substitute the placeholder +> first: +> +> ```bash +> PROJECT_ROOT="$(pwd)" +> sed "s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT|g" systemd/ledmatrix.service \ +> | sudo tee /etc/systemd/system/ledmatrix.service > /dev/null +> sudo systemctl daemon-reload +> sudo systemctl enable ledmatrix.service +> sudo systemctl start ledmatrix.service +> ``` ## Service Management