feat(starlark,on-demand): the third-party fixes worth taking, plus a Home Assistant MQTT bridge (#538)

* feat(starlark,on-demand): the third-party fixes worth taking, plus an MQTT bridge

Analysis of ant456/ledmatrix-fixes-repo, a third-party collection of
patches and services built while running this project on Starlark apps
under MQTT control. Its patches are whole-file copies taken against an
older tree, so applying them as written would revert #523's frame
pacing, #534's display() bool returns and the GitHub token masking in
plugins_manager.js. Three of its claimed fixes are already in main, and
its api_v3 Starlark routes are #535's. What follows is the rest --
verified against current code, and reimplemented where the patch's
approach did not hold up.

**On-demand display.** `pinned` reached the controller from the API, was
stored on it and republished in the status payload, but never narrowed
the rotation -- a pinned request still cycled every mode its plugin
owns. Right for a sports plugin, whose modes are views of one subject;
wrong for a plugin whose modes are unrelated, which is every Starlark
app. Now honoured, and it survives a restart.

Restarting while on-demand was active loaded *only* the on-demand
plugin, so normal rotation had nothing to return to for the life of the
process -- and a restart mid-session is routine, since that is how an
update is applied. The panel came back cycling one plugin's modes with
no way out but clearing the cache by hand. Every enabled plugin loads
now; on-demand still resumes on its saved mode.

Stop requests are exempt from the duplicate guards on purpose, so that a
second click stops a mode a race left running -- which means consuming
the mailbox is the only thing that ends one. It was never consumed, so
the same stop was re-read and re-processed on every poll, forever. Both
paths now share one compare-before-delete helper.

**Starlark rendering.** `extract_schema` parsed the source with a regex,
which can only see option lists written out literally: an app whose
dropdown is filled from a live API call inside `get_schema()` came back
empty, and the config form offered nothing to pick. Now runs `pixlet
schema`, which executes the app, and falls back to the parser when
Pixlet is absent, too old for the subcommand, or the app fails to run.
The third-party patch replaced the parser outright and hardcoded
/usr/local/bin/pixlet; this keeps the fallback and the binary search.

A `|` in a config value was dropped by a shell-metacharacter filter,
though the command is a list with no shell involved -- and apps do use
it as a separator inside one value. The key went missing silently and
the app rendered its own "not configured" screen with nothing to say
why. And a 0-byte render was reported as success: Pixlet exits 0 and
writes nothing when an app has no content, which read downstream as a
working app drawing a black panel.

**Starlark display.** `display()` ignored the mode it was called with,
so a specific app could not be addressed. It now accepts `display_mode`
-- which is the whole mechanism, since the controller inspects the
signature before passing it. Found while there: `_select_next_app` ran
only while `current_app` was unset, so with several apps installed the
first was picked once and shown forever while the rest were rendered on
schedule and never displayed. And `enable_scrolling` was missing, so
multi-frame apps were called once per rotation slot and never advanced
past frame one.

**GET /api/v3/display/modes.** Every mode that can be requested
on-demand, with the plugin that owns it. Nothing exposed this, so
anything driving the display from outside the web UI read each plugin's
manifest.json off disk and reimplemented PluginManager's fallbacks. It
also triggers discovery, which is otherwise lazy and normally happens
because a person opened the dashboard.

**integrations/mqtt_bridge.** Home Assistant control over MQTT
Discovery: a mode select, a stop button, power, brightness. Rewritten
against the API rather than the filesystem, so it needs no read access
to config.json and cannot drift from the web UI. paho-mqtt 2.x
VERSION2, TLS, an availability topic that is also the last will, and
secrets from the environment.

**Two opt-in extras.** A DNS single-request unit, for glibc's parallel
A/AAAA lookup stalling ~5s per name on routers that answer only the A
query -- which makes any plugin calling an external API slow and
Starlark apps, which have a render timeout, fail outright. And a Pixlet
config editor: a script you run and Ctrl+C rather than the third-party
version's always-on unauthenticated Flask service, since it stops the
display for the length of a session. Neither is installed by default.

Long Starlark app names now wrap instead of overflowing their card.

115 new tests across 5 files. Also unblocked
test_starlark_display_contract.py, which was silently skipping wherever
fcntl is absent. Whole suite: no new failures against main.

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

* fix(mqtt_bridge): the five issues Codacy flagged on this branch

All in the new bridge, all real:

  * requests floor was 2.31.0, which carries CVE-2024-35195,
    CVE-2024-47081 and CVE-2026-25645. Raised to >=2.33.0,<3.0.0, which
    is what the project's own requirements.txt already pins.
  * `import time` was never used.
  * `"mqtt_password": None` in DEFAULTS read as a hardcoded credential.
    It is the "no password configured" default; marked nosec B105, the
    convention used elsewhere in the repo.

Also dropped an unused `build_app` from the display-modes test imports.

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

* fix: the review findings on this PR

Nine of CodeRabbit's ten, plus the CodeQL alert. The tenth is wrong and
is answered below.

**One bad config section blanked the whole mode list.**
`/display/modes` read `full_config.get(plugin_id, {}).get('enabled')`,
so a non-dict under a plugin id -- a shape DisplayController already
guards, so it happens -- raised AttributeError mid-loop and answered 500
with no modes at all. Every MQTT bridge entity is built from that list.
Now skipped with a warning.

**The DNS scripts reported success they had not earned.** Three separate
paths: `resolvconf -u` failing was swallowed by `|| true`; the
systemd-resolved branch exited 0 without applying anything, so the
oneshot unit recorded success while the workaround was inactive; and the
installer's `|| echo` turned a failed start into "installation
complete." with exit 0. All three now fail loudly. `single-request` is a
glibc resolv.conf option with no resolved.conf equivalent, so on those
hosts the honest answer is that it cannot be applied.

A NetworkManager-generated resolv.conf is regenerated on connection
changes, not only at boot, and the unit is oneshot with RemainAfterExit
-- so the option can vanish mid-boot with nothing to put it back. Now
detected and stated plainly rather than implied to be permanent.

**`Before=` does not order a manual restart.** It only orders units
already in the same transaction, so `systemctl restart ledmatrix` could
bypass the fix. install_dns_fix.sh now writes a ledmatrix.service
drop-in with Wants= and After=. Wants=, not Requires=: a DNS workaround
failing should not stop the display.

**The Pixlet editor's `--lan` is gone.** `pixlet serve` has no
authentication, and a printed warning is not access control. Loopback
only, with the SSH port-forward in the header where the flag used to be
documented -- SSH does the authenticating and nothing is left listening.

**The MQTT example config now defaults to TLS** on 8883. The installer
copies it verbatim, and without TLS the broker password and every
command cross the network in cleartext. A plaintext broker is still
supported and documented, and the bridge warns once at startup when a
password is configured without TLS.

**Not taken: "the upstream Pixlet CLI has no `schema` subcommand."**
Upstream tidbyt/pixlet has none, but `scripts/download_pixlet.sh`
installs `tronbyt/pixlet`, whose `cmd/schema.go` is
`schema [PATH]` -> JSON on stdout, built on
`runtime.NewAppletFromPath`, so it does execute `get_schema()`. That is
exactly what extract_schema_via_pixlet calls. A binary without the
subcommand exits non-zero and falls back to the source parser, which is
already covered by a test.

**CodeQL stack-trace exposure: not taken either.** I removed `details`
first and that broke
test_web_error_detail.py::test_no_api_v3_handler_discards_its_exception,
which enforces `describe_exception` across all ~75 handlers -- written
because a device with failing storage answered "see logs for details"
from the log viewer itself. describe_exception redacts credentials; the
trade-off is the project's and is already made. Restored, with the
reasoning in a comment.

11 new tests. Whole suite: no new failures against main, 4127 passed.

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

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

test/test_api_v3_display_modes.py

@@ -0,0 +1,157 @@
+"""GET /api/v3/display/modes -- the list of modes an on-demand request can name.
+
+Anything driving the display from outside the web UI needs two things that no
+existing endpoint gave it: the set of display modes, and which plugin owns each
+one. /plugins/installed carries neither, so callers read every plugin's
+manifest.json off disk and reimplemented PluginManager's own fallbacks.
+"""
+
+import json
+from unittest.mock import MagicMock
+
+import pytest
+
+from test._api_v3_test_helpers import (  # noqa: F401 - fixtures
+    api_v3_client, api_v3_module,
+)
+
+
+MANIFESTS = {
+    'clock-simple': {'name': 'Simple Clock', 'display_modes': ['clock-simple']},
+    'football-scoreboard': {
+        'name': 'Football Scoreboard',
+        'display_modes': ['nfl_live', 'nfl_recent', 'nfl_upcoming'],
+    },
+    'ledmatrix-weather': {'name': 'Weather', 'display_modes': ['weather']},
+}
+
+CONFIG = {
+    'clock-simple': {'enabled': True},
+    'football-scoreboard': {'enabled': True},
+    'ledmatrix-weather': {'enabled': False},
+}
+
+
+@pytest.fixture
+def client(api_v3_module, api_v3_client):
+    pm = api_v3_module.api_v3.plugin_manager
+    pm.plugin_manifests = MANIFESTS
+    pm.discover_plugins = MagicMock(return_value=list(MANIFESTS))
+    pm.get_plugin_display_modes = MagicMock(
+        side_effect=lambda pid: MANIFESTS[pid]['display_modes'])
+    api_v3_module.api_v3.config_manager.load_config = MagicMock(return_value=CONFIG)
+    return api_v3_client
+
+
+def _modes(response):
+    return {m['mode']: m for m in response.get_json()['data']['modes']}
+
+
+class TestTheModeListing:
+    def test_enabled_plugins_contribute_every_mode(self, client):
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert set(modes) == {'clock-simple', 'nfl_live', 'nfl_recent', 'nfl_upcoming'}
+
+    def test_each_mode_names_its_plugin(self, client):
+        """on-demand/start's find_plugin_for_mode fallback cannot see generated
+        modes, so the caller has to send plugin_id -- it must come from here."""
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert modes['nfl_live']['plugin_id'] == 'football-scoreboard'
+
+    def test_disabled_plugins_are_left_out_by_default(self, client):
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert 'weather' not in modes
+
+    def test_disabled_plugins_can_be_asked_for(self, client):
+        """They are still valid on-demand targets: the controller enables them
+        for the duration of the request."""
+        modes = _modes(client.get('/api/v3/display/modes?include_disabled=1'))
+        assert modes['weather']['enabled'] is False
+
+    def test_a_single_mode_plugin_is_labelled_with_its_own_name(self, client):
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert modes['clock-simple']['name'] == 'Simple Clock'
+
+    def test_a_multi_mode_plugin_labels_each_mode_distinctly(self, client):
+        """There is no per-mode name anywhere, and three modes all called
+        "Football Scoreboard" are not a usable dropdown."""
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert modes['nfl_live']['name'] == 'nfl_live'
+        assert modes['nfl_live']['plugin_name'] == 'Football Scoreboard'
+
+
+class TestItWorksForACallerThatNeverOpensTheDashboard:
+    def test_discovery_is_triggered(self, client, api_v3_module):
+        """Discovery is lazy and normally runs because a person loaded the
+        dashboard; a bridge or script would otherwise get an empty list."""
+        client.get('/api/v3/display/modes')
+        api_v3_module.api_v3.plugin_manager.discover_plugins.assert_called_once()
+
+    def test_no_plugin_manager_is_a_clean_error(self, api_v3_module, api_v3_client):
+        api_v3_module.api_v3.plugin_manager = None
+        response = api_v3_client.get('/api/v3/display/modes')
+        assert response.status_code == 500
+        assert response.get_json()['status'] == 'error'
+
+    def test_a_plugin_with_no_declared_modes_still_appears(self, client, api_v3_module):
+        """Its mode is its own id -- the same fallback the controller uses."""
+        pm = api_v3_module.api_v3.plugin_manager
+        pm.plugin_manifests = {'starlark-apps': {'name': 'Starlark Apps', 'display_modes': []}}
+        pm.get_plugin_display_modes = MagicMock(return_value=[])
+        api_v3_module.api_v3.config_manager.load_config = MagicMock(
+            return_value={'starlark-apps': {'enabled': True}})
+
+        modes = _modes(client.get('/api/v3/display/modes'))
+        assert modes['starlark-apps']['plugin_id'] == 'starlark-apps'
+
+
+class TestOneBadConfigSectionDoesNotBlankTheList:
+    """config.json can hold a non-dict under a plugin id.
+
+    DisplayController guards the same shape, so it happens in practice. Here it
+    used to raise AttributeError mid-loop and answer 500 with no modes at all --
+    and the MQTT bridge builds every one of its entities from this list, so one
+    hand-edited section would empty the Home Assistant dropdown.
+    """
+
+    @pytest.fixture
+    def client_with_bad_section(self, api_v3_module, api_v3_client):
+        pm = api_v3_module.api_v3.plugin_manager
+        pm.plugin_manifests = MANIFESTS
+        pm.discover_plugins = MagicMock(return_value=list(MANIFESTS))
+        pm.get_plugin_display_modes = MagicMock(
+            side_effect=lambda pid: MANIFESTS[pid]['display_modes'])
+        api_v3_module.api_v3.config_manager.load_config = MagicMock(return_value={
+            'clock-simple': {'enabled': True},
+            'football-scoreboard': "true",          # a string, not an object
+            'ledmatrix-weather': {'enabled': True},
+        })
+        return api_v3_client
+
+    def test_the_endpoint_still_answers(self, client_with_bad_section):
+        assert client_with_bad_section.get('/api/v3/display/modes').status_code == 200
+
+    def test_the_healthy_plugins_are_still_listed(self, client_with_bad_section):
+        modes = _modes(client_with_bad_section.get('/api/v3/display/modes'))
+        assert 'clock-simple' in modes and 'weather' in modes
+
+    def test_the_bad_section_is_treated_as_disabled(self, client_with_bad_section):
+        modes = _modes(client_with_bad_section.get('/api/v3/display/modes'))
+        assert 'nfl_live' not in modes
+
+    def test_a_failure_is_reported_the_way_every_other_handler_reports_one(
+            self, api_v3_module, api_v3_client):
+        """describe_exception, per test_web_error_detail's contract -- an
+        opaque "see logs for details" is what that test exists to prevent."""
+        api_v3_module.api_v3.plugin_manager.discover_plugins = MagicMock(
+            side_effect=RuntimeError("disk is gone"))
+        resp = api_v3_client.get('/api/v3/display/modes')
+        assert resp.status_code == 500
+        assert 'disk is gone' in resp.get_json()['details']
+
+    def test_credentials_in_the_exception_are_redacted(self, api_v3_module, api_v3_client):
+        """describe_exception is what makes returning detail safe."""
+        api_v3_module.api_v3.plugin_manager.discover_plugins = MagicMock(
+            side_effect=RuntimeError("GET https://x/y?api_key=SEC123 failed"))
+        body = api_v3_client.get('/api/v3/display/modes').get_json()
+        assert 'SEC123' not in json.dumps(body)