Library scanners become plugins — the bridge half (host, wire, kit, console, packaging) #59
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: unom/punktfunk#59
Reference in New Issue
Block a user
Implements
design/library-scanner-plugins-implementation-plan.mdM0–M4 and M6. The six in-hostscanners can now be lifted out into plugins without anything downstream noticing. The scanners are
still here and still working — this is the bridge half; the removal release (WP6.4) is separate.
Two plugins are already built against this and shipping green:
lutris ·
heroic.
@punktfunk/plugin-kit@0.3.0is published.mainis merged in and fully contained — conflict-free, CI green on every job.Commits
a418d285launch.rs; art proxy resolves any id3d4a65998728d90ebd383f18ce8f3e9e91fa32fba1b8627ed20858796f07bd94launcher_ui)The load-bearing idea
Store claims (D2).
PUT /library/provider/{p}?store=steamlets a plugin claim a store, so itsentries get the deterministic
<store>:<external_id>ids the built-in scanner produced — not opaquecustom:<hex>ones. That is what keeps GameStream FNV app ids, Moonlight pins, client art caches andthe operator's
library-scanners.jsondisabled state valid across the migration. While a claim isheld the matching built-in scanner is skipped, so the two never double-list; removing the plugin
releases the claim and the built-in comes straight back.
The identity chain is one string end to end — repo name → npm package → plugin id → provider id →
store claim → scanner id — which is why the plugin repos were renamed to match (
xbox, notxbox-app).The merge with #58 — please read this bit
#58 hardened the art proxy in the same three files this branch rewrote, in the opposite direction:
it narrowed what the host will read from disk, while WP1.2 widened what counts as a local art
path so an extracted scanner's covers can be served at all. Resolved so the widening goes through
the gate, never beside it. Everything #58 added is kept unchanged.
The subtle one:
art_roots()was empty on non-Windows, which was correct whileis_local_art_pathwas Windows-shaped — Playnite is Windows-only, so nothing on a POSIX host was ever classified as
local art and the confinement had nothing to confine. Once WP1.2 classifies POSIX paths, an empty
root list is not "secure by default": it serves no plugin art on Linux, i.e. every cover the
lutris and steam plugins emit. It now includes
$HOME— the exact analogue of the Windows users base#58 already ships — and that is not the load-bearing control anyway: a value still needs an image
extension, must canonicalize to a real regular file inside a root and outside the config dir, and
must contain image bytes.
Also:
file://is converted to a path before the confinement check, so the check and the readsee the same path — percent-decoding before canonicalization, so
%2e%2ecan't hide from thetraversal check. Pinned by a test.
The second collision with #58: launcher tiles
D4 promised entries that open the launcher (Steam Big Picture, Heroic, Lutris) and said the
non-Steam ones would ride the
commandkind. #58 then madelaunch.kind = "command"operator-only,so a plugin publishing one is refused. Both changes are individually right and jointly left a hole:
steam_uiwas the only launcher kind a plugin could publish, so a Heroic or Lutris tile wasunreachable.
6f07bd94adds a typedlauncher_uikind valued by store id — one kind, because every launcher butSteam has exactly one UI to open. D1 is preserved: the plugin names a launcher, the host builds the
command. Platform-gated and validated inbound, so an unsupported value is a 400 the author can
act on rather than a tile that does nothing when clicked. Windows launchers are deliberately absent
until each has a verified activation.
Four bugs found on the way
is_steam_launchgated on asteam://URI (gamescope.rs). Asteam_uilauncher entrycarries no URI, so it would have skipped both gamescope's
--steammode and the B1single-instance free — on a box autologged into game mode the nested Steam would see the first
instance and exit, crashing the spawn. Now tests the first token.
prep_forstripped acustom:prefix, so a claimed entry would have silently lost itsper-title prep. Now resolved through the shared id mapping.
steam_uiwas missing from the host-resolved launch kinds named inprivileged_field's doccomment and in the 403 a plugin sees. Prose only — the check is a denylist — but a plugin author
reading that error would have concluded their launcher entries were refused.
GameFormhad no way to mark an entry as a launcher (a WP4.3 item that was missed). Added,and
formFromround-trips it — without which editing a launcher entry would silently demote itto a game, which is exactly the bug that file's own comment warns about.
What IS verified
CI green on
6f07bd94:ci / rust,ci / rust-arm64,ci / web,ci / docs-site,windows / build(x86_64 and aarch64),apple / swift,android.On
.21:punktfunk-host435 passed / 0 failed — including #58's H-2 confinement tests and thenew
file://andlauncher_uiones — full workspace tests, workspaceclippy --all-targets -- -D warnings,cargo fmt --all --check, and the OpenAPI drift test.plugin-kit: tsc clean, 56 tests. Console: orval + paraglide regen, tsc,
vite build,check-i18nat 604 messages for en + de.
What is NOT verified — accept these knowingly
Everything below is code-reviewed and test-covered but has not been exercised on real hardware.
None of it is reachable from CI.
types and lint and was only visible rendered; the new sources surface, the schema-driven settings
drawer and the launcher checkbox deserve the same scepticism.
windows-host.ymldid not run here — thegreen Windows jobs are the client builds).
steam_ui/epic/goglaunch resolution isWindows-only code whose unit tests only compile there.
.isschange needs a fresh install, an upgrade, andan upgrade with
PunktfunkScriptingdeliberately disabled — that last one is the case thefresh-vs-upgrade probe exists for. deb/rpm/sysext need package builds.
reproduces its scanner needs a box with that launcher installed. No plugin has passed it yet,
including the two already published.
the steam plugin is the first that will, and it is not built. What is newly possible today is
hand-adding a Heroic or Lutris tile from the console.
plugin-kit-v0.3.0is tagged ata1b8627eon this branch, so the published package's source onlyreaches
mainwhen this lands. Its documented launch-kind table predateslauncher_uiand willcatch up in the next kit release.
Not in scope
WP6.4 (deleting the six scanner modules) is the removal release, after all six plugins are pinned
and the bridge has had a quiet field window. WP5.6 index pins are per-plugin PRs to
punktfunk-plugin-index, which you merge. Four plugins remain: steam, gog, epic, and xbox (stillgated on the S1 LocalService probe).
M2 of design/library-scanner-plugins-implementation-plan.md. Everything a library scanner plugin needs is now expressible over the API; all additive. WP2.1/2.2 — store claims (D2). library.json gains a v2 shape ({entries, claims}) that loads the v1 bare array unchanged and is written on the first mutation. PUT /library/provider/{p}?store=<s> claims a store for a provider: its entries then surface with deterministic <store>:<external_id> ids and the store's own badge instead of opaque custom:<id> ones. That identity is the whole point — entry ids, GameStream FNV app ids, client art caches and Moonlight pins all survive a title moving from an in-host scanner to a plugin. One provider per store (409 otherwise); DELETE releases; an empty reconcile does NOT (a store can legitimately have zero titles). While a claim is held, all_games() skips the matching built-in scanner, so the two never double-list during the bridge. WP2.3 — DetectHint gains steam_appid and env_marker, the two store-derived signals the host used to read for itself. Without them a steam plugin's lease tracking would drop from reaper-exact to dir-prefix, and Heroic-under-Proton would lose the only signal that works. Malformed markers are dropped, not honoured — this feeds a path that can end processes. WP2.4/2.5 — role: game|launcher on the entry shapes (serde-default, skipped when default), and a steam_ui launch kind valued bigpicture|desktop that opens the Steam client itself. Validated inbound as well as at launch. WP2.6 — GET/PUT /library/scanners generalizes to SOURCES: built-in scanners minus claimed ones, plus claimed stores, plus any provider with entries. The same library-scanners.json disabled-set backs all of them and the ids match by construction, so a user's disabled state carries over verbatim through the whole migration. A disabled plugin source has its entries filtered at read time, exactly like a disabled scanner. WP2.7/2.8 — plugin registration gains a category field (the console keeps library plugins out of the nav); index entries gain categories and per-platform detect probes, evaluated existence-only into CatalogEntry.detected so the host never re-grows per-store knowledge. Index SCHEMA stays 1 — additive. WP2.9 — OpenAPI + SDK regenerated on Linux; kit wire widened (LaunchSpec.kind is now a plain string documented against the host's vocabulary — closes G3), and ProviderClient.reconcile takes an optional store and returns the host's echoed entries so a caller can detect a pre-M2 host silently ignoring the claim. Also fixes a bug the S3 spike turned up: is_steam_launch gated on a steam:// URI, so a steam_ui launcher entry would have skipped BOTH gamescope's --steam mode and the B1 single-instance free — on a box autologged into game mode, the nested second Steam would see the first and exit, crashing the spawn. It now tests the first token. Gates on .21: workspace tests green (punktfunk-host 425 passed), workspace clippy -D warnings clean, cargo fmt --all --check clean, OpenAPI drift test green. plugin-kit: tsc clean, 20 tests pass.M3 of design/library-scanner-plugins-implementation-plan.md. Target shape: a first-party scanner plugin is its parsers plus a scan function. WP3.1 — a parsers module under the new ./library subpath, porting what the six in-host scanners hand-rolled: text VDF/ACF, the BINARY shortcuts.vdf KeyValues walker with its CRC-32 appid derivation and the 64-bit rungameid composition, read-only SQLite (bun:sqlite, immutable=1 so a scan can never take a lock or spawn WAL sidecars next to a launcher's live database), a reg.exe wrapper, capped readers, the path-confinement join that keeps a crafted goggame-*.info from pointing a launch at an arbitrary program, Steam root/library discovery, art location helpers, and a fetch helper carrying the host's no-redirect anti-SSRF posture. Every parser is total: a missing launcher or a truncated file degrades to "no titles", never to a throw. Two deliberate departures from the Rust originals, both about the Windows runner's account: steam root discovery now also reads HKLM Valve\Steam InstallPath (a non-default install dir was previously uncovered), and the registry wrapper refuses HKCU outright — as LocalService that is not the operator's hive, so reading it would silently look like "not installed". WP3.2 — GET/PUT /__config on the kit's UI server, so a plugin with settings does not ship an SPA (closes G8). GET answers {schema, value}: the derived JSON Schema and the raw operator-authored config. PUT validates by decoding and only then persists RAW, so defaults are never baked into the file. The handler is split out as makeConfigHandler and driven directly in tests. WP3.3 — defineLibraryPlugin wires SyncEngine (poll + fs-watch + debounce), the store-claiming reconcile, launcher entries appended to every sync, a UI server serving only __config under category "library" (which keeps six installed scanners out of the console nav), and the standard detect/scan/uninstall CLI verbs. It warns ONCE when a pre-M2 host silently ignores the store claim — that degradation is otherwise invisible except as duplicated titles. M0/S2 is recorded here as a committed fixture rather than prose. Two findings the original spike missed because deriving a schema does not exercise it: withDecodingDefaultKey takes an Effect, not a thunk — a thunk type-checks, derives fine, and dies at decode time; and a checked schema (Schema.Int) nests its annotations under allOf, so a form must merge those branches. Both are pinned. plugin-kit: version 0.3.0, tsc clean, 46 tests pass (16 ported parser tests, 10 config/derivation). Publishing (WP3.4) is deferred — it needs a tag and a push.One plugin = one repo, matching the house pattern (playnite, rom-manager and virtualhere are already each their own repo with their own biome/bunfig/tsconfig /CI). The implementation plan's WP5.0 had proposed a single workspace repo for all six library scanners; this is the piece that makes the split cost nothing. Everything the six scanners share is already published rather than adjacent: the parsers and defineLibraryPlugin live in @punktfunk/plugin-kit/library, so repo boundaries are irrelevant to them. Fixtures are not shared in practice either — the Rust scanners build theirs inline in code, there are no fixture files, and the one genuinely cross-plugin builder (binary shortcuts.vdf) is already in this package's own tests. A pga.db fixture is useless to the epic plugin. The parity harness was the exception: generic across all six, and parked in the shared repo the plan assumed. It moves here. What it is: the acceptance gate for an extracted scanner. Ported unit tests pin the PARSERS; they do not prove the plugin reproduces the scanner it replaces. A plugin that parses perfectly and emits steam:440.0 instead of steam:440 breaks every Moonlight pin on the host and no parser test notices. punktfunk-plugin-steam parity --snapshot before.json # host on its built-in punktfunk-plugin-steam parity --compare before.json # offline; exits non-zero --compare runs the plugin's own scan rather than requiring it to be installed first, so a mismatch is visible before anything is published and the run is repeatable while you fix it. Three judgement calls in the diff, each pinned by a test: * art is compared by PRESENCE, not value. The representation legitimately changes on extraction (a host-relative proxy path or inlined data: URL becomes a file:// path or a CDN URL), so comparing values would fail every run for no reason. Losing an art kind fails; gaining one does not. * launcher entries (role: "launcher") are reported separately instead of as unexpected extras — the built-in scanner had no concept of them, so they can never be in a baseline. An ORDINARY title the scanner never had still fails, which is what catches a bad tool filter. * absent and empty are the same thing in metadata: the host omits empty lists and nulls, so a plugin sending genres: [] has not changed anything. plugin-kit: tsc clean, 56 tests pass (10 new).Design D4 promised entries that open the LAUNCHER — Steam Big Picture, Heroic, Lutris — and the plumbing for it landed in M2/M4: the `role` field, the `steam_ui` kind, the console's Launchers rail. But nothing could flow through it for anything except Steam. D4 said the other launchers would ride the `command` kind. The 2026-08-05 review then made `launch.kind = "command"` operator-only (it is handed to a shell), so a plugin publishing one is refused with a 403. The two changes are individually right and jointly leave a hole: `steam_ui` was the only launcher kind a plugin could publish, so a Heroic or Lutris tile was unreachable. New `launcher_ui` kind, valued by store id. One kind rather than one per store because every launcher except Steam has exactly a single UI to open; Steam keeps its own kind because it genuinely has two. D1 is preserved — the plugin names a launcher, the host builds the command, and no shell string crosses the wire: heroic -> the same native-or-Flatpak resolution the `heroic` game kind uses, minus --no-gui and minus the URI, so the window itself opens lutris -> bare `lutris`, which opens the window (the URI form is `lutris_id`) Platform-gated to what this host can actually resolve, and validated INBOUND: a value naming a launcher this OS cannot open is a 400 the plugin author can act on, not a tile that silently does nothing when a user clicks it. Windows launchers (Epic, GOG Galaxy, Xbox app) are deliberately absent — each needs its own verified activation and a guess would ship exactly that dead tile. Also closes a WP4.3 item I under-delivered and did not flag: the console's add/edit form had no way to mark an entry as a launcher, so even hand-adding one was impossible. It now has the checkbox — and `formFrom` round-trips it, without which editing a launcher entry would silently demote it to a game, which is the precise bug that file's own comment warns about. Gates on .21: punktfunk-host 435 passed / 0 failed (two new), workspace clippy -D warnings clean, cargo fmt --all --check clean, OpenAPI drift green. Console: orval + paraglide regen, tsc clean, check-i18n at 604 messages for en + de. Still unproven on hardware: no launcher tile has been clicked on a real host. The steam plugin (the first to emit one) is not built yet.