feat: initial ROM & emulator manager plugin (M0–M5)

A punktfunk-plugin-* package that scans ROM directories, maps them to
emulators, fetches box art, and reconciles them into the host game library
under provider id `rom-manager` — with a console-hosted web UI.

Engine (pure, unit-tested core):
- Table-driven platform registry (~25 consoles) + emulator registry with
  best-effort per-OS detection (PATH / Flatpak / known paths) and RetroArch
  core discovery.
- Scanner with disc folding (m3u/cue/gdi), archive gating, excludes.
- No-Intro title parsing + optional per-platform region dedupe.
- Security-critical quoting seam: POSIX single-quote + Windows double-quote
  with hostile-name refusal; ROM filenames never reach a shell un-quoted.
- Pure desired-state reconcile (stable external_ids, scale guard, fingerprint
  skip) → full-replace PUT /library/provider/rom-manager.

Box art (like Steam ROM Manager): SteamGridDB primary (portrait/hero/logo/
header, fuzzy match, operator API key) behind a provider seam, with keyless
libretro-thumbnails as the zero-setup fallback (`auto` default).

UI: console-hosted via the SDK `servePluginUi` (zero plugin-side auth) with a
plugin-local REST/SSE API and a self-contained React SPA (Setup / Emulators /
Games / Sync). Standalone password-gated fallback for host-only installs.

CLI: scan / detect / preview / sync / uninstall / set-password.

48 engine tests, typecheck + biome clean, SPA builds. Verified end-to-end:
scan → detect → reconcile PUT, fingerprint idempotence, and the standalone
UI serving SPA + REST.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

test/emulators.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import {
+	type DetectEnv,
+	detectEmulator,
+	emulatorById,
+} from "../src/emulators.js";
+import type { Os } from "../src/quote.js";
+
+const env = (o: {
+	os?: Os;
+	which?: Record<string, string>;
+	files?: string[];
+	flatpaks?: string[];
+	dirs?: Record<string, string[]>;
+}): DetectEnv => ({
+	os: o.os ?? "linux",
+	which: (c) => o.which?.[c] ?? null,
+	fileExists: (p) => (o.files ?? []).includes(p),
+	flatpakInstalled: (id) => (o.flatpaks ?? []).includes(id),
+	listDir: (p) => o.dirs?.[p] ?? [],
+	expandPath: (p) =>
+		p
+			.replace(/^~/, "/home/u")
+			.replace(/%APPDATA%/, "C:\\Users\\u\\AppData\\Roaming")
+			.replace(/%LOCALAPPDATA%/, "C:\\Users\\u\\AppData\\Local"),
+});
+
+const retroarch = emulatorById("retroarch")!;
+const ppsspp = emulatorById("ppsspp")!;
+const dolphin = emulatorById("dolphin")!;
+
+describe("detectEmulator", () => {
+	test("RetroArch on PATH, cores scanned + quoted exe token", () => {
+		const d = detectEmulator(
+			retroarch,
+			env({
+				which: { retroarch: "/usr/bin/retroarch" },
+				dirs: {
+					"/home/u/.config/retroarch/cores": [
+						"snes9x_libretro.so",
+						"mgba_libretro.so",
+						"notes.txt",
+					],
+				},
+			}),
+		);
+		expect(d?.via).toBe("path");
+		expect(d?.exeToken).toBe("'/usr/bin/retroarch'");
+		expect(d?.coresDir).toBe("/home/u/.config/retroarch/cores");
+		expect(d?.cores).toEqual(["mgba", "snes9x"]);
+	});
+
+	test("RetroArch via Flatpak when not on PATH", () => {
+		const d = detectEmulator(
+			retroarch,
+			env({
+				flatpaks: ["org.libretro.RetroArch"],
+				dirs: {
+					"/home/u/.var/app/org.libretro.RetroArch/config/retroarch/cores": [
+						"snes9x_libretro.so",
+					],
+				},
+			}),
+		);
+		expect(d?.via).toBe("flatpak");
+		expect(d?.exeToken).toBe("flatpak run org.libretro.RetroArch");
+		expect(d?.appId).toBe("org.libretro.RetroArch");
+		expect(d?.cores).toEqual(["snes9x"]);
+	});
+
+	test("Windows path with spaces is double-quoted", () => {
+		const d = detectEmulator(
+			ppsspp,
+			env({
+				os: "windows",
+				files: ["C:\\Program Files\\PPSSPP\\PPSSPPWindows64.exe"],
+			}),
+		);
+		expect(d?.via).toBe("file");
+		expect(d?.exeToken).toBe(
+			'"C:\\Program Files\\PPSSPP\\PPSSPPWindows64.exe"',
+		);
+	});
+
+	test("returns null when not installed", () => {
+		expect(detectEmulator(dolphin, env({}))).toBeNull();
+	});
+});