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>
This commit is contained in:
+151
@@ -0,0 +1,151 @@
|
||||
// The plugin's configuration model (design §9) — the single source of truth for the sync engine,
|
||||
// editable by hand (headless boxes) or by the web UI. Everything the engine needs is derivable from
|
||||
// this file plus a directory scan; the `resolveConfig` helper fills defaults so the rest of the code
|
||||
// works against a fully-populated shape.
|
||||
|
||||
import type { EmulatorDef } from "./emulators.js";
|
||||
import type { Platform } from "./platforms.js";
|
||||
|
||||
/** A ROM root: a directory paired with the platform its files belong to (design §5). */
|
||||
export interface RomRoot {
|
||||
/** Absolute directory to scan. */
|
||||
dir: string;
|
||||
/** Platform id (a key into the resolved platform registry). */
|
||||
platform: string;
|
||||
/** Per-root glob ignore patterns (`*.sav`, `bios/**`). */
|
||||
excludes?: string[];
|
||||
}
|
||||
|
||||
/** A per-platform launch override — replaces the platform's built-in default emulator/core. */
|
||||
export interface PlatformLaunch {
|
||||
emulator: string;
|
||||
core?: string;
|
||||
extraArgs?: string;
|
||||
}
|
||||
|
||||
/** A per-game override, keyed by `external_id` (`snes/Chrono Trigger (USA).sfc`). */
|
||||
export interface GameOverride {
|
||||
/** Skip this ROM entirely. */
|
||||
exclude?: boolean;
|
||||
/** Override the resolved emulator/core/args for just this title. */
|
||||
emulator?: string;
|
||||
core?: string;
|
||||
extraArgs?: string;
|
||||
/** Override the displayed title. */
|
||||
title?: string;
|
||||
/** Override the box-art portrait URL. */
|
||||
art?: string;
|
||||
}
|
||||
|
||||
export interface SyncOptions {
|
||||
/** Interval poll in minutes (watchers are unreliable on SMB/NFS — poll is the primary trigger). */
|
||||
pollMinutes: number;
|
||||
/** Enable fs watching (an accelerator on top of the poll). */
|
||||
watch: boolean;
|
||||
/** Debounce window for coalescing watch/poll-triggered rescans (ms). */
|
||||
debounceMs: number;
|
||||
/** Platform ids to region-dedupe ("one entry per title", design §5) — default none. */
|
||||
dedupeRegions: string[];
|
||||
/** Region preference order for dedupe (best first). */
|
||||
regionPriority: string[];
|
||||
/** Warn in the UI above this entry count (design §8 scale guard). */
|
||||
warnEntries: number;
|
||||
/** Hard cap — truncate with a loud report above this many entries. */
|
||||
maxEntries: number;
|
||||
/** Attach `prep`/`undo` that kills the emulator at session end ("close emulator when stream ends"). */
|
||||
closeOnEnd: boolean;
|
||||
}
|
||||
|
||||
/** Which art source to use (design §7, revised): SteamGridDB (like Steam ROM Manager) or the keyless
|
||||
* libretro-thumbnails fallback. `auto` = SteamGridDB when a key is set, else libretro. */
|
||||
export type ArtProviderChoice = "auto" | "steamgriddb" | "libretro";
|
||||
|
||||
export interface ArtOptions {
|
||||
/** Fetch box art at all. */
|
||||
enabled: boolean;
|
||||
/** Art source selection (default `auto`). */
|
||||
provider: ArtProviderChoice;
|
||||
/**
|
||||
* SteamGridDB API key (free, from steamgriddb.com profile preferences). Unlocks full portrait +
|
||||
* hero + logo + header art with fuzzy title matching. Absent → the keyless libretro fallback.
|
||||
*/
|
||||
steamGridDbKey?: string;
|
||||
}
|
||||
|
||||
export interface UiOptions {
|
||||
/**
|
||||
* Fallback standalone mode (design §9): serve the UI on a fixed, possibly non-loopback port behind
|
||||
* a password instead of via the console proxy. For host-only installs without the console.
|
||||
*/
|
||||
standalone: boolean;
|
||||
/** Standalone bind port. */
|
||||
port: number;
|
||||
/** Standalone bind address (defaults to loopback; a non-loopback bind REQUIRES a password). */
|
||||
bind: string;
|
||||
/** scrypt password hash (`scrypt$<saltB64>$<hashB64>`), required for a non-loopback standalone bind. */
|
||||
passwordHash?: string;
|
||||
}
|
||||
|
||||
/** The on-disk config as authored (all optional — `resolveConfig` fills the rest). */
|
||||
export interface RawConfig {
|
||||
roots?: RomRoot[];
|
||||
/** Per-platform launch overrides, keyed by platform id. */
|
||||
platformLaunch?: Record<string, PlatformLaunch>;
|
||||
/** Per-game overrides, keyed by `external_id`. */
|
||||
gameOverrides?: Record<string, GameOverride>;
|
||||
/** Operator-added / overriding platform defs (merged over the built-ins by id). */
|
||||
platforms?: Platform[];
|
||||
/** Operator-added / overriding emulator defs (merged over the built-ins by id). */
|
||||
emulators?: EmulatorDef[];
|
||||
sync?: Partial<SyncOptions>;
|
||||
art?: Partial<ArtOptions>;
|
||||
ui?: Partial<UiOptions>;
|
||||
/** Dev/M0 acceptance flag: reconcile one hardcoded entry so the round-trip is observable. */
|
||||
devEntry?: boolean;
|
||||
}
|
||||
|
||||
/** The fully-resolved config the engine consumes. */
|
||||
export interface Config {
|
||||
roots: RomRoot[];
|
||||
platformLaunch: Record<string, PlatformLaunch>;
|
||||
gameOverrides: Record<string, GameOverride>;
|
||||
platforms?: Platform[];
|
||||
emulators?: EmulatorDef[];
|
||||
sync: SyncOptions;
|
||||
art: ArtOptions;
|
||||
ui: UiOptions;
|
||||
devEntry: boolean;
|
||||
}
|
||||
|
||||
export const DEFAULT_SYNC: SyncOptions = {
|
||||
pollMinutes: 15,
|
||||
watch: true,
|
||||
debounceMs: 2000,
|
||||
dedupeRegions: [],
|
||||
regionPriority: ["USA", "World", "Europe", "Japan"],
|
||||
warnEntries: 2000,
|
||||
maxEntries: 5000,
|
||||
closeOnEnd: false,
|
||||
};
|
||||
|
||||
export const DEFAULT_UI: UiOptions = {
|
||||
standalone: false,
|
||||
port: 47993,
|
||||
bind: "127.0.0.1",
|
||||
};
|
||||
|
||||
/** Fill defaults over an authored config so the rest of the engine sees a total shape. */
|
||||
export const resolveConfig = (raw: RawConfig): Config => ({
|
||||
roots: raw.roots ?? [],
|
||||
platformLaunch: raw.platformLaunch ?? {},
|
||||
gameOverrides: raw.gameOverrides ?? {},
|
||||
platforms: raw.platforms,
|
||||
emulators: raw.emulators,
|
||||
sync: { ...DEFAULT_SYNC, ...raw.sync },
|
||||
art: { enabled: true, provider: "auto", ...raw.art },
|
||||
ui: { ...DEFAULT_UI, ...raw.ui },
|
||||
devEntry: raw.devEntry ?? false,
|
||||
});
|
||||
|
||||
/** The empty starting config for a fresh install (no roots yet). */
|
||||
export const emptyConfig = (): Config => resolveConfig({});
|
||||
Reference in New Issue
Block a user