musicdl-catalog-sync-suite/Music_Server/docs/superpowers/plans/2026-04-22-music-server-lan-plugin.md

Music Server LAN Plugin Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a second MusicFree plugin that prefers a NAS LAN endpoint when reachable, while keeping the existing Music_Server plugin unchanged and publish both through the subscription manifest.

Architecture: Keep the current music_server.js path and behavior intact. Add a new music_server_lan.js asset with its own platform/name and LAN-first endpoint selection logic, then expose both assets from Music_Server plugin routes and the subscription manifest.

Tech Stack: Node-style MusicFree plugin JS, Node test runner, FastAPI plugin routes, unittest.

---

Task 1: Lock route publishing behavior with tests

Files:

• Modify: D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_plugin_routes.py

• Add failing tests for a second plugin asset route and a manifest that returns both plugin entries.

• Run python -m pytest D:\source\musicdl-catalog-sync-worktrees\Music_Server\tests\test_plugin_routes.py -q and confirm failure.

Task 2: Lock LAN-first plugin behavior with tests

Files:

• Create: D:\source\musicdl-catalog-sync-worktrees\MusicFree\keep-alive-master\Music_Free\music_server_lan.test.cjs

• Add failing tests covering lanBaseUrl exposure, LAN probe success choosing LAN base URL, LAN probe failure falling back to public base URL, and relative media URL joining against the chosen active base URL.

• Run node --test D:\source\musicdl-catalog-sync-worktrees\MusicFree\keep-alive-master\Music_Free\music_server_lan.test.cjs and confirm failure.

Task 3: Implement and publish the new plugin

Files:

• Create: D:\source\musicdl-catalog-sync-worktrees\MusicFree\keep-alive-master\Music_Free\music_server_lan.js

• Create: D:\source\musicdl-catalog-sync-worktrees\Music_Server\src\music_server\plugin_assets\music_server_lan.js

• Create: D:\source\musicdl-catalog-sync-worktrees\MusicFree\release\music_server_lan_latest.js

• Modify: D:\source\musicdl-catalog-sync-worktrees\Music_Server\src\music_server\routes\plugins.py

• Modify: D:\source\musicdl-catalog-sync-worktrees\MusicFree\release\music_server_subscription.json

• Implement LAN-first base URL resolution in the new plugin only, using GET /healthz reachability with short cache and fallback to the public base URL.

• Expose the new plugin from Music_Server at its own JS route and add it to the shared subscription manifest without removing the original plugin.

• Copy the released LAN plugin file into the subscription-facing release location.

Task 4: Verify end to end

Files:

• Verify only

• Run the focused MusicFree LAN plugin tests.

• Run the plugin route tests.

• Fetch the manifest locally and confirm it lists both plugin URLs.

• If requested, sync/deploy the updated Music_Server plugin asset and manifest to NAS and restart the service.