Active Plugins and Plugin Library pages (M5 part 2b-2)

[txoof-bot]

Part of #238 (M5 part 2b-2). Built on #244 (part 2b-1), which is built on #241. Merge in that order; each PR then moves to main by itself.

What changed

Two new pages in the web interface, linked from the home page:

• Active Plugins (/plugins): every [[plugin]] block in the config file, in file order (the order the plugins take turns). Each row shows its status ("On", "Off", "Needs settings: lat, lon, email", or "Not used: has errors" with the line and message) and has Switch on / Switch off, Up / Down buttons, and Remove, which asks first.
• Plugin Library (/library): every plugin type with its description, except default and debugging. Choosing one asks for a name (a free one is suggested, e.g. "Word clock 2") and adds it at the end of Active Plugins.

How a change works:

• Saved in the config file at once (with part 2b-1's code), then PaperPi reloads the file (paperpi run hands the scheduler's reload to the web server), so it applies at once.
• Hand edits that were not applied yet stay in the file and apply together; the page then says "Your hand edits to the config file were applied too." (as agreed). PaperPi tells the web interface which file text it uses after each load (new Config.text); a password saved by the web interface does not count as a hand edit.
• A plugin with required settings is added switched off; the add page lists those settings with their help text (for met_no this includes "Your own, real email address"). Until the settings page (part 3a), the page says to type them into the config file and shows its path.
• A change is refused, with the reason on the page, when: the block was changed meanwhile; the file can't be changed safely; the file has a problem that stops PaperPi from using it (PaperPi would stay on the last good copy, so the change would not apply); or the file would get too large.

Choices I made without asking:

• Switch on is greyed out while settings are missing (a plugin that is on but misses settings can still be switched off).
• Plain HTML forms with a page reload after each click, no htmx yet.
• The "added" note only shows a name that is really in the list, so a link can't put other text on the page; "removed" shows no name.
• Two blocks with the same name: the second one shows "Not used: has errors" with PaperPi's message.

Docs: README web section, docs/decisions/web-interface.md new "Plugin list pages" section, plugin-interface.md and writing-plugins.md updated.

Size: +918/−26, over the ~800 guideline. About 400 lines are tests; the review rounds added most of them (and the fixes), and small review fixes stay in their PR.

Area

web (src/paperpi/web/), core (src/paperpi/cli.py wiring, src/paperpi/config.py Config.text), docs.

Tests

New tests/test_web_plugins.py (26 tests): each page and change, comments kept, hand edits (after a reload, after a web change, password save, editor without a known text), required settings, names that can't be used, broken plugin types, repeated names, a file PaperPi can't use, log-in and other-website check on every new form, odd requests, permissions, and one test against the real running web server. tests/test_cli.py checks that paperpi run passes the reload and the file text; tests/test_config.py checks Config.text.

• uv run pytest passes (1165 tests)
• uv run ruff check . passes
• Hardware tests: not needed

Images

No screenshots: the Pi has no browser. To look at the pages: uv run paperpi run --config <file> and open http://<Pi's IP>:8080/plugins.

Review

• Review agents' comments answered: four reviews (code quality, tests, security, docs) ran locally before the first push; their fixes are the second commit. Left out on purpose (small): the Library add route loads the plugin list twice for an unknown type; the name field's maxlength="100" is written in the page.

Only txoof approves and merges this PR.

🤖 Generated with Claude Code